Argonne National Laboratory

Experimental Physics and
Industrial Control System

2002  2003  2004  2005  2006  2007  2008  2009  2010  <20112012  2013  2014  2015  2016  2017  2018  2019  2020  Index 2002  2003  2004  2005  2006  2007  2008  2009  2010  <20112012  2013  2014  2015  2016  2017  2018  2019  2020 
<== Date ==> <== Thread ==>

Subject: Re: class library header file naming and install conventions
From: Ralph Lange <Ralph.Lange@gmx.de>
To: core-talk@aps.anl.gov
Date: Tue, 15 Mar 2011 17:49:39 +0100
On 15.03.2011 17:20 Jeff Hill wrote:
I would encourage considering the use of a standard tool like
doxygen, I think once you start writing in-line documentation it should
make future maintenance easier, although I've rarely used it myself
because introducing it after-the-fact is hard.

Such tools have been around for a long time. People were using them on the
VAX when I started here in 1986. I'm sure they have learned a thing or two
since then so perhaps I should look closer at doxygen. The argument for use
of doxygen type programs is that programmers are more likely to work on
their programming language source files, and so if we store the doc there
also then maybe they will keep it current. There can also be a standard,
consistent, format. The downside maybe is that every manual reads like a
reference manual, and we are less likely to have a tutorial. We are maybe
more likely to create human friendly documentation with concept structured
indexes and html tables if the html is structured by a human?

We won't (ever) win a Pulitzer with our documentation, either way.

Doxygen (which looks and works a lot like Javadoc) creates very nice reference documentation from comments in the source files, which is especially nice for library APIs that you want other people to use.
There are IDEs that help you create doxygen for C/C++ very similar to helping you create Javadoc.
The internal link references in the html code are created automatically by doxygen. These are always relative, so that you can move around the created doc.

But again: Doxygen is for creating code documentation. Tutorials, user guides, and fiction should use other tools.

~Ralph


References:
class library header file naming and install conventions Jeff Hill
Re: class library header file naming and install conventions Andrew Johnson
RE: class library header file naming and install conventions Jeff Hill

Navigate by Date:
Prev: Re: class library header file naming and install conventions Andrew Johnson
Next: Re: class library header file naming and install conventions Andrew Johnson
Index: 2002  2003  2004  2005  2006  2007  2008  2009  2010  <20112012  2013  2014  2015  2016  2017  2018  2019  2020 
Navigate by Thread:
Prev: Re: class library header file naming and install conventions Andrew Johnson
Next: Re: class library header file naming and install conventions Bruce Hill
Index: 2002  2003  2004  2005  2006  2007  2008  2009  2010  <20112012  2013  2014  2015  2016  2017  2018  2019  2020 
ANJ, 02 Feb 2012 Valid HTML 4.01! · Home · News · About · Base · Modules · Extensions · Distributions · Download ·
· Search · EPICS V4 · IRMIS · Talk · Bugs · Documents · Links · Licensing ·