Hi :) > So does anyone have any objections to 'doxygenificaiton' of the code? :)
None here, quite the opposite :) > Use Javadoc style comments as opposed to QT style comments. IMHO it's > easier on the eyes. For example: > /** > * This does foobar > */ > and *not*: > /*! > * This does foobar > */ Agreed to that (first proposal). > Doxygen accepts commands in both the forms "\foobar" or "@foobar". I > believe that "@foobar" is easier to read as it stands out more (from > things like escape characters and the / character used in commenting) > without being an eyesore either. For example > /** > * This function does foobar > * @param ob The object to foobar > * @todo Handle multitile objects > */ > as opposed to > /** > * This function does foobar > * \param ob The object to foobar > * \todo Handle multitile objects > */ Agreed to first proposal too. > Make use of the "@file foobar.c" directive at the top of code files. I > think files should have their purpose clearly outlined in order to keep > code organized. For example: > /** @file foobar.c > * Handle foobaring. > * @note Don't put baz here. > */ > at the start of the file Idem. > Have JAVADOC_AUTOBRIEF set to TRUE and comment appropriately. > Doxygen supports both full and brief descriptions. Explicitly specifying > each tends to look poor when looking at the comment manually, however by > using JAVADOC_AUTOBRIEF, it automatically makes the first sentence of > the description the brief description. This requires comments to be > written to fit this, with the first sentence of the description being a > summary of what the function/etc. does. Nice feature, yeah, agreed we should use it. > Another thing, is that in order to link to global variables or global > typedefs in doxygen comments, one needs to write it as either "::foobar" > or as "#foobar". Personally I don't like either much, but we should > decide which to use. Maybe "::foobar"? It's coherent with namespace naming. I'd say we should do that progressively, while changing functions and such, instead of everything in one time. Nicolas _______________________________________________ crossfire mailing list [email protected] http://mailman.metalforge.org/mailman/listinfo/crossfire
