On 2009-09-21 10:09+0200 Werner Smekal wrote:
> Hi,
>>
>> One thing I've been doing in my professional projects of late, is using
>> doxygen. I find the standard doxygen style that depends on all the '*'
>> characters to be really ugly, but since I mostly code in C++, there is the
>> alternative of ///, which annoys me, but not as badly as " * ", plus those
>> dorky header/trailer tokens.
>>
>> I've not tried doxygen on a C code base before, so I'm not sure if there
>> are
>> options that are more visibly appealilng than the standard/default.
>> Without
>> looking into it a bit first, I'm not in a postion to propose a specific
>> style
>> for function comment blocks. But I thought I throw out the doxygen option
>> in
>> case anyone else is interested in that, and able to summarize some of the
>> options.
>
> Since I use myself doxygen a lot for my own code, I started to "doxyfy" the
> PLplot source code. I added a Doxygen configuration file and changed on
> source code file (plpage.c) so that Doxygen can filter the description for
> the functions. I copied the output of doxygen to the net:
>
> http://www.miscdebris.net/plplot_doxygen/
>
> You need to click "File List" on the left and then "plpage.c" to see some
> source code documentation
> I did that, since I regularly wander around the plplot core code not finding
> what I need and I know that doxygen makes that a lot easier with cross
> references and so on. Question is now,
>
> 1) if everybody agrees to "doxyfy" the plplot source code
> 2) if everybody agrees how I documented the functions
>
> If it's ok, then I start the doxyfying process and everybody else is welcome
> to join.
Hi Werner:
I think this would be a superb and powerful replacement for our normal
in-source documentation. I have a small amount of experience with doxygen
via the libLASi project and was much impressed by it. Following your
instructions above to refer to plpage (and the functions defined within that
source code) confirmed just how useful this could be to us. I must
emphasize this should be seen as excellent supplement to our already
existing DocBook form of API documentation. doxygen is good at giving the
quick details an experienced PLplot library developer needs plus all the
important internal cross-references for our implementation. In contrast,
our DocBook form of API documentation can be more general; it should be
aimed more for external programmers who are using our API but who have no
need to know about the internal details of our implementation of that API.
So, yes please, go ahead as far as I am concerned with "doxygenating" our
in-source documentation. However, I do have some further comments and
suggestions.
* We mostly do this already with our in-source documentation, but I wanted
to mention the general principle of keeping the doxygen form of that
documentation as short as possible for each of our functions (e.g., use
one sentence rather than a paragraph to describe the function or one of
its parameters). This documentation should be considered a short reminder
aimed at experienced PLplot library developers and not something more
comprehensive that you might expect from our DocBook form of API
documentation. I think the current level of detail we have for plgspa
(http://www.miscdebris.net/plplot_doxygen/plpage_8c.html#ac9d7c35262ab1c80cc1ed9bf15f7f128)
is just about right. So this is not a criticism of what we have now.
Instead, I just wanted to state the principle to be clear how this
documentation potentially differs in brevity from the DocBook form of our
API documentation.
* For each of our functions please put in a cross-reference to the website
form of documentation for that same function that is generated by DocBook
in order to give everybody access to the broader overview that implies.
* Currently those DocBook-generated URL's are in the versioned form
http://plplot.sourceforge.net/docbook-manual/plplot-html-5.9.5/*.html.
Regardless of how this doxygen project goes, I plan to change those URL's
to the unversioned form, i.e.,
http://plplot.sourceforge.net/docbook-manual/plplot-html/*.html since it
should help other websites as well as our doxygen-generated one to have a
constant URL to refer to for our html documentation generated by DocBook.
Anyhow, assume the unversioned form when doing the cross-references from
the doxygenized code comments.
* The URL's for the current form of our doxygen documentation are a mess (as
can be seen from the form of plgspa URL above). Is there a configuration
parameter to shorten those to something that is comprehensible (and thus
guaranteed to be constant) such as
.../plplot_doxygen/plpage.c_plgspa.html? I think we should
cross-reference every doxygen function reference from our corresponding
DocBook API documentation, but this is only practical with a non-changing
form of URL for everything that doxygen documents. You may have that
already, but a comprehensible URL without a bunch of random numbers in it
is useful in many other ways as well.
* Location. The generation of documentation in doxygen form should be part
of our release tarball and also our SourceForge website. I would be happy
to help out there by doing the appropriate changes to our build system and
making an additional script to populate our website with the results.
To move forward with this, please send me the doxygen commands you recommend
to generate the html version of our doxygen results in our build tree.
I can take it from there.
Alan
__________________________
Alan W. Irwin
Astronomical research affiliation with Department of Physics and Astronomy,
University of Victoria (astrowww.phys.uvic.ca).
Programming affiliations with the FreeEOS equation-of-state implementation
for stellar interiors (freeeos.sf.net); PLplot scientific plotting software
package (plplot.org); the libLASi project (unifont.org/lasi); the Loads of
Linux Links project (loll.sf.net); and the Linux Brochure Project
(lbproject.sf.net).
__________________________
Linux-powered Science
__________________________
|