Re: [crossfire] Code Doxygenification
Hello. Having thought some, I suggest we try to have all documentation (including the doc/Developers directory) regrouped into Doxygen. Unless I'm mistaking, we can ask Doxygen to include some information from external sources, so it shouldn't be hard to merge eg object types, and such. Also, stuff like what one fields does exactly (example: sp is used as spellpoints, but also as exit coordinate) should be directly in the code I think. Having only one documentation entry point is IMO what we should aim for. Nicolas ___ crossfire mailing list crossfire@metalforge.org http://mailman.metalforge.org/mailman/listinfo/crossfire
Re: [crossfire] Code Doxygenification
Hello. I just did all files in the common/ subdirectory :) (fixed indent and comments) Ok, i didn't comment *all* parameters, i did feel stupid for writing obvious things. But resulting documentation looks nice ^_- Now, I warn you: I will track and hang, after some smacking, anyone committing code not indented correctly, and/or without comments *evil grin* Nicolas ___ crossfire mailing list crossfire@metalforge.org http://mailman.metalforge.org/mailman/listinfo/crossfire
Re: [crossfire] Code Doxygenification
Agreed. One thing we should perhaps check is if the terms of use for the sf.net compile farm/shell server allows us to run doxygen on it, not really sure it would but it would be nice if we could. If nobody else is able to, I could run a nightly cron job (which won't run unless the doxygen config or a code file changes in the 24 hour period) for it around 10:00 UTC or so, however I wouldn't be able to host it myself so I would need to upload it somewhere else. Anyone have any suggestions for options for this? Shouldn't that documentation be on the website? *grins evilly towards poor Rick* But I do agree having documentation online would be nice. Nicolas ___ crossfire mailing list crossfire@metalforge.org http://mailman.metalforge.org/mailman/listinfo/crossfire
Re: [crossfire] Code Doxygenification
Nicolas Weeger (Laposte) wrote: Agreed. One thing we should perhaps check is if the terms of use for the sf.net compile farm/shell server allows us to run doxygen on it, not really sure it would but it would be nice if we could. If nobody else is able to, I could run a nightly cron job (which won't run unless the doxygen config or a code file changes in the 24 hour period) for it around 10:00 UTC or so, however I wouldn't be able to host it myself so I would need to upload it somewhere else. Anyone have any suggestions for options for this? IIRC, the sourceforge folks only want the compile farm used for interactive use - no cron jobs, etc. Plus I seem to recall some odd things regarding access to web area (or maybe it was SVN) from the compile farm itself - something with it being inside the sourceforge network/firewall made things different. I'd have no problem setting up a cron job on my home system and copying the data somewhere, but that somewhere is a trickier issue. sourceforge provides web space, but also requires that every web page for the project has the sourceforge logo. I'm not sure if there is an easy way to modify doxygen to include that. I could host the data myself, but it would be better for it to be on one of the more official crossfire sites. ___ crossfire mailing list crossfire@metalforge.org http://mailman.metalforge.org/mailman/listinfo/crossfire
Re: [crossfire] Code Doxygenification
Mark Wedel wrote: IIRC, the sourceforge folks only want the compile farm used for interactive use - no cron jobs, etc. Plus I seem to recall some odd things regarding access to web area (or maybe it was SVN) from the compile farm itself - something with it being inside the sourceforge network/firewall made things different. Actually, they do at least currently allow cron jobs: http://sourceforge.net/docman/display_doc.php?docid=762group_id=1#cron And in fact some of their servers (/x86-linux2 and //x86-freebsd1/) do have doxygen installed already: http://sourceforge.net/docman/display_doc.php?docid=762group_id=1#devel_tools The real issue with using the sf.net compile farm to my understanding is outbound connectivity as it has no real way to automatically send it to whatever is hosting it. Therefore I'm thinking we'd just have to do it on one of our own boxes. sourceforge provides web space, but also requires that every web page for the project has the sourceforge logo. I'm not sure if there is an easy way to modify doxygen to include that. Doxygen does allow manual modification of the html headers :) See: http://www.stack.nl/~dimitri/doxygen/config.html#cfg_html_header and: http://www.stack.nl/~dimitri/doxygen/doxygen_usage.html Alex Schultz ___ crossfire mailing list crossfire@metalforge.org http://mailman.metalforge.org/mailman/listinfo/crossfire
Re: [crossfire] Code Doxygenification
I think that the proposed changes are fine. Updating the functions as they are changed or other nearby functions are changed works, but the end result is that it means it can take a very long time for all the functions to be documented. And if the goal/hope is to have some coherent documentation available, getting it done sooner vs later is probably good. We can sort of look at the other various code cleanups going on - fixing indentation has been going on for quite a while, and still not done. Some functions really are not changing much (the arch.c file gets occasional new function added, but I don't think some of the functions in there have been modified for years), so it could be a very long wait for change to happen. OTOH, doing this cleanup or indentation fixes is something that can be done in small doses. I know that for myself, if I only have 30 minutes to spend, I may not going on a coding project, knowing I will be unable to finish it in that time. However, I could certainly document several functions in that time period, etc. Also, do we have any plans for putting this doxygenification online anyplace? I imagine this could be done automatically (have a cron job that generates the documents and then upload them to some server nightly or something). One nice thing about doing something like that is that then the results are more visible ___ crossfire mailing list crossfire@metalforge.org http://mailman.metalforge.org/mailman/listinfo/crossfire
Re: [crossfire] Code Doxygenification
Mark Wedel wrote: OTOH, doing this cleanup or indentation fixes is something that can be done in small doses. I know that for myself, if I only have 30 minutes to spend, I may not going on a coding project, knowing I will be unable to finish it in that time. However, I could certainly document several functions in that time period, etc. This sort of thing is part of the reason I was thinking about doxygenification myself, as I was finding I had numerous short periods of time that I wouldn't be able to get code done it but could do a little documentation or something in. :-) Also, do we have any plans for putting this doxygenification online anyplace? I imagine this could be done automatically (have a cron job that generates the documents and then upload them to some server nightly or something). One nice thing about doing something like that is that then the results are more visible Agreed. One thing we should perhaps check is if the terms of use for the sf.net compile farm/shell server allows us to run doxygen on it, not really sure it would but it would be nice if we could. If nobody else is able to, I could run a nightly cron job (which won't run unless the doxygen config or a code file changes in the 24 hour period) for it around 10:00 UTC or so, however I wouldn't be able to host it myself so I would need to upload it somewhere else. Anyone have any suggestions for options for this? Alex Schultz ___ crossfire mailing list crossfire@metalforge.org http://mailman.metalforge.org/mailman/listinfo/crossfire
Re: [crossfire] Code Doxygenification
Hi, On Sunday 24 December 2006 10:09 Nicolas Weeger (Laposte) wrote: 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. OTOH, #foobar is coherent with URI (HTML etc.) and Javadoc. My 2 cents :) -- Christian Hujer Free software developer mailto:[EMAIL PROTECTED] http://www.riedquat.de/ PGP Fingerprint: 03DE 4B72 4E57 A98D C79B 24A5 212E 0217 0554 CCAB pgppa5FofLw9t.pgp Description: PGP signature ___ crossfire mailing list crossfire@metalforge.org http://mailman.metalforge.org/mailman/listinfo/crossfire
Re: [crossfire] Code Doxygenification
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 crossfire@metalforge.org http://mailman.metalforge.org/mailman/listinfo/crossfire
[crossfire] Code Doxygenification
Hi everyone, So does anyone have any objections to 'doxygenificaiton' of the code? :) Also, we need to agree on a standard form of doxygen comments to use as there are a few different syntax variations it accepts. In addition, if we do agree that the code should be 'doxygenificatated', I think it would be a good idea to document this in the coding style docs. Personally I'd advocate the following commenting style: --- 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 */ --- 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 */ --- 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 --- 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. (see: http://www.stack.nl/~dimitri/doxygen/config.html#cfg_javadoc_autobrief ) --- 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. I suggest one looks at http://www.stack.nl/~dimitri/doxygen/docblocks.html for more information on what doxygen accepts. Alex Schultz ___ crossfire mailing list crossfire@metalforge.org http://mailman.metalforge.org/mailman/listinfo/crossfire
