> Andre Poenitz <[EMAIL PROTECTED]> writes: > > | I think it would be prudent to split patches into "documentation stuff" > | and "small code changes", maybe even to abstain from the small code changes > | at all.
I will try to separate these things then, or at least put in \todo comments where the code looks iffy and then go back to clean code later. Doxygen can generate a page of \todo items, which makes these things easy to find. On Thu, 2002-11-07 at 04:17, Lars Gullik Bjønnes wrote: > Also, until now we have said to document the interfaces in .h and > implementation in .C. If we are still going to follow that, and I > think we should, the patch must be redone and move the comments to the > .h file. I do not feel that this is sensible. Please let me explain. Doxygen provides for two levels of comments. Let me provide examples: short form: /// Load a lyx document file long form: /** * Load the LyX document file, stored in .lyx format. * After loading, the document is completely represented in memory * using the internal LyX representation. * \param filename the name of the file to read, with complete path. * \return true if any error occurred * \author someone who wrote this function */ 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. 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. The long form of documentation is quite easily accessible through the doxygen documentation, when and as required. 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. Ben.
