Re: [bug-recutils] Document for librec

[Jose E. Marchesi]

             Please use doxygen to generate man3 and html for src/rec.h
             If you want, I can do it for you
         
         A patch would be welcome.  But first I want to be sure the markup is 
not
         too overwhelming.  Could you please send us an example?  For example,
         how would be the header comment of rec_db_query using doxygen?
    
    I'd welcome documentation for the API At the same time I'd be disappointed 
if
    it came in the form of doxygen, javadoc or the like.  API documentation 
created 
    with such tools are almost always next to useless.   The list of arguments 
shows
    nothing more than one would gleem by looking at the interface, and the 
@brief if
    the developer even bothers with it is - er well - brief.  

The high-level API (rec_db_*) is already documented in rec.h in the form
of comments.  This way a developer only has to open the header file and
search for the prototype of the function she is interested in.  If the
doxygen markup is not too overwhelming then I probably would not object
to reformat the current comments.  I have no idea how the markup
language looks like nor how invasive it is.

Of course the documentation in the header file has to be terse and
limited: if we wanted to provide other stuff like example programs using
the API then we would probably have to create a new texinfo manual or a
new chapter "Hacking gnu recutils" in the existing manual.

For this reason I don't think it is a good idea to generate man3
manpages from the header comments.  It would be better to generate them
from a texinfo manual.