Re: [pdf-devel] Extracting documentation from sources

[jemarch]

Hi Juan Pedro.

   In GHM 2008 I told jemarch about using a documentation extractor from 
   the sources for the project. I told him about Doxygen, which is quite 
   full-featured and produces very nice output, but does not generate 
   texinfo documentation, which is a requirement for GNU projects.

   I have done some research and found this http://josefsson.org/gdoc/ It 
   seems to be quite good for C projects. What do you think? In case 
   Doxygen where considered (I find it syntax and features better) we could 
   generate Docbook with Doxygen and then Texinfo with docbook2tx anyway.

   I don't want to bother you with the typical: "hey you do things the way 
   I like", but I just thought that using a documentation generator from 
   the sources could highly improve productivity and documentation quality, 
   and leaves no need for API consistency checks.

The idea of using doxygen or some other similar tool to keep the
reference documentation is quite attractive.

I would be happy to introduce the use of such a tool in GNU PDF but,
due to the workflow we use (first design the API of the module and
document it in the refman, then implement it) we really need to have
some place to document the API before to write any code. If we can
find a solution for this then to use a doxygen-like tool would be
really useful. Any idea?

BTW, gdoc seems to be an interesting tool. For this purpose I use a
really simple awk script in GNU Ferret [1]. The texinfo documentation
is embedded in both header and implementation source files [2][3] and
the refman is generated in make doc time.

[1]
http://cvs.savannah.gnu.org/viewvc/ferret/utils/docstr2texi.in?revision=1.5&root=ferret&view=markup
[2]
http://cvs.savannah.gnu.org/viewvc/ferret/src/oc.h?revision=1.7&root=ferret&view=markup
[3]
http://cvs.savannah.gnu.org/viewvc/ferret/src/oc.c?revision=1.9&root=ferret&view=markup