Curious About Documentation Comment Locations

[andrewauclair]

I recently started using ReSharper C++ at work and it shows all the comments in the Poco headers in the intellisense. I don't believe the normal Visual Studio intellisense does this unless the comments are XML.

What I'm noticing is that all the comments are wrong because the comments are below the function they refer to and not above. Was this decision made for some other documentation tool? I think I've only ever seen tools check comments above a function.

[aleks-f]

Poco comments are written for documentation generation with PocoDoc. In addition to the text being under the declarations, there are also no special tagging keywords in the comments.

For some strange reason, people seem to think that the description of a class or function should be above the declaration, which is an equivalent of a chapter text coming before the chapter title, or a book title being placed at the end of the book - it makes no sense. Poco documentation incompatibility with most documentation tools is a known issue, and there are no plans to do anything about it. Long time ago, there was a script to generate doxygen documentation for poco, should still be somewhere in the contributing directory.

[andrewauclair]

Huh, I never thought of them that way, but I think that now makes more sense than above. Too bad that became the standard.