bug-recutils
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [bug-recutils] Document for librec


From: John Darrington
Subject: Re: [bug-recutils] Document for librec
Date: Thu, 31 Oct 2013 13:35:03 +0100
User-agent: Mutt/1.5.21 (2010-09-15)

On Thu, Oct 31, 2013 at 01:19:22PM +0100, Jose E. Marchesi wrote:
     
     Hi.
         
         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.  

Doxygen encourages the person writing it (which is usually the developer of the 
library)
to concentrate too much on the details and mechanics of the API rather than the 
big picture, and explaining to a user WHY one would want to use a function or 
set 
a variable to a particular state.    To the developer, these things are obvious 
- 
after all he is intimately familiar with the library.  Hence it seems to him
pointless to mention them.  Instead he does what doxygen demands, and thinks the
job is done.

So please produce some API documentation in the form of english prose but NOT 
using Doxygen.

I'd be ever so gratefull.

J'
     

-- 
PGP Public key ID: 1024D/2DE827B3 
fingerprint = 8797 A26D 0854 2EAB 0285  A290 8A67 719C 2DE8 27B3
See http://sks-keyservers.net or any PGP keyserver for public key.




reply via email to

[Prev in Thread] Current Thread [Next in Thread]