Ben Stanley <[EMAIL PROTECTED]> writes:
| The first style is a summary comment, and I use these in class
| declarations, i.e. header files. The second comment type is the in depth
| documentation, which I place above the function definition. When viewing
| the HTML documentation provided by Doxygen, the class API is first
| described in summary form, using the /// comments, and later each
| function is described in depth using the /** ... */ form. There is a
| hyperlink from the short to the long.
|
| Placing the documentation closer to the code which it describes means
| that it is also more likely to be maintained as the code is modified.
| This is an important consideration.
Well... these doxygen headers do not describe the code, and if they do
they shouldn't. They should describe the api. And most of the
developers will not even run doxygen to create the html doc.
| It is possible to place the /** */ form in the header file, but then the
| headers will become quite bloated, and this will increase compilation
| time.
To me this is a void argument.
| The long form of documentation is quite easily accessible through
| the doxygen documentation, when and as required.
that is.. if you have created the doxygen documentation.
| In my experience with doxygen, the arrangement of short comments in the
| header with longer comments in the source works better than placing long
| comments in the header files. I find the doxygen api documentation is
| much easier to browse than the source when looking things up.
But then it should matter for you should it?
I am not convinced, IMO we should keep the doxygen doc in the header
files.
--
Lgb
