[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.