On Mon, Sep 21, 2009 at 10:09:22AM +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, since I chose to only add documention > for functions with doxygen descriptions. > > 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.
Werner, As a general principle I think this is a good idea and good coding practice. I've not used doxygen, although I am aware that it seems to be the "standard" for this kind of thing. The markup comment style is a little quirky, but I can live with that. I'll hold off any crustify changes to the code until we decide on this. At some stage (if we do this) it would be nice to generate at least some of the documentation using the same markup. This is likely to be non-trivial, but would save a huge amount of duplication, particularly in terms of function prototypes, arguments and return values. I've no idea if this is possible. Andrew ------------------------------------------------------------------------------ Come build with us! The BlackBerry® Developer Conference in SF, CA is the only developer event you need to attend this year. Jumpstart your developing skills, take BlackBerry mobile applications to market and stay ahead of the curve. Join us from November 9-12, 2009. Register now! http://p.sf.net/sfu/devconf _______________________________________________ Plplot-devel mailing list Plplot-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/plplot-devel
