[CF-Devel] Re: Code documentation?

Mon Nov 17 20:17:54 CST 2003

On Mon, 2003-11-17 at 06:39, Andreas Vogl wrote:

>

      Code documentation is always a good idea.

     >

     >

      Since the CFJavaEditor shows up on the link provided,

     >

      this reminds me that the editor is pretty well documented

     >

      in javadoc style.

     >

      I don't have a problem with doxygen being used to format

     >

      CFJavaEditor sources, however I would like developers who

     >

      might be working on the java code to write javadoc comments

     >

      (in case there is any difference, which I'm not sure about).

     >

     >

      Anyways, I have added a javadoc build target to to the ant

     >

      build file for the editor. Javadocs can now be generated by

     >

      the command "ant doc".

     >

     >

      As an example, javadocs from current CVS can be downloaded from:

     >

      http://home.in.tum.de/~vogl/crossfire/CFJavaEditor_docs.zip

     >

     >

      (This is just a one-time example. I don't plan to update the link

     >

      when code changes occur).

     >

     >

      AndreasV

     >

I was posting the source code via doxygen as a test trial but if people
want to actually add more comments to the code because of this - this is
good.  Up till now I have just run doxygen against the raw source code
but I can commit the doxyfiles used for each project (editor, server,
client) to allow anyone to generate the documentation if this is wanted
so that people can use the tool more.  Really I haven't been around long
enough to decide anything like that however. As far as I understand it
it there is markup you can use which will appear as comments in
plaintext but will be fancier or more featureful when running doxygen. 
The tool also will do other formats than html if this is desired.
I have been maintining these things manually but I had planned on
automating this if it was a popular feature - it is real easy to
generate these code mini-sites once you have templates.  You only need
doxygen and graphviz and the sourcecode so it could be scheduled to run 
against a copy of CVS and served up automatically (say on sourceforge or
real-time).
As for javadoc comments, I am pretty sure that Doxygen can manage to do
the right thing with javadoc type commenting (RTFM I expect of course -
I haven't dome more than skim it really) so the two tools should be
pretty cohabitable but I would suggest that some comment to this effect
should be in the sourcecode or developer guide for the Java editor if
there is a particular style or whatever of documenting desired.  This
would go for the CF developer guidelines too.

_______________________________________________
crossfire-devel mailing list

     crossfire-devel at lists.real-time.com

     https://mailman.real-time.com/mailman/listinfo/crossfire-devel