Doxygen comments
Closed this issue · 2 comments
I've started work on this, but there are some tricky issues remaining:
- trailing comments are not supported (they're ignored)
- special comment categories can mess things up (see more below)
Right now, comments are always applied to the next entity that appears in the file. However, doxygen specifies that certain comments can be directed elsewhere, e.g.
- def directs the comment to the following macro
- defgroup directs the comment block to a group
- example directs the comment block to a different source file
- file directs the comment to the current source file
- internal directs the comment to nowhere
- mainpage directs the comment to the main doxygen page
- name directs the comment to a member group
- page directs the comment to a documentation page
- privatesection directs the comment to a section
- protectedsection
- publicsection
- subpage
- tableofcontents
- section
- subsection
- subsubsection
- paragraph
Also, if the group-delimiters @{ or @} appear in a doxygen comment, that comment should be ignored.
Note that we only want these doxygen commands to cause the current block to be ignored. This means that, if a blank line or non-doxygen comment line is encountered, the comment should be cleared.
Another issue is that @Class is meant to direct a comment to a specific class, but there is currently no way of attaching the comment to a class that might not even be defined yet.
The FileInfo struct in vtkParseData will have to be modified to hold some doxygen-specific information, and its current comment fields can be deprecated. To start, all that is needed is an array to hold all the unclaimed "class" comments.
Issue no longer relevant here, code for the parser has moved to VTK repository.