Comment by cjfd

I don't have experience with this in Rust but have come to passionately hate this kind of documentation in other language. I think all of pydoc, javadoc and, doxygen are all garbage. If one could apply them sensibly it would not be so much of a problem but then you have documentation nazis who force you to document every method and every parameter. This leads to hightly enlightening prose documentation that the get_height method "gets the height", and that its return value is the height. A more high level problem with this is that you get documentation that is just as fragmented as the code and where the high level usage of things is not explained at all. Also it clutters the code with many highly trivial remarks.