On Thu, 2003-10-16 at 11:48, Laurent Sansonetti wrote:
> On Wed, 2003-10-15 at 22:36, Rodrigo Moya wrote:
> > I add some documentation when I've got time, as does Gonzalo also
> > sometimes. But nothing really consistent, so please, feel free to work
> > on it :-)
>
> OK, so I'm starting right now ;-)
And here is the first patch.
I added missing entries for functions described in the 'libgda API
reference' section.
While visiting the code, I saw that some existing entries were not
following the normal notation (used in glib, gtk...), e.g.:
/**
* foo_init
* @args: arguments to initialize the foo library. (1)
*
* Initializes the foo library, with the given @args. (2)
*
* Returns: %TRUE on success, %FALSE otherwise. (3)
*/
1) no-capitalized sentence, ended with a dot.
2) capitalized sentence with third person verb, ended with a dot.
3) no-capitalized sentence, ended with a dot, and using %XXX where XXX
can be TRUE, FALSE, NULL...
Therefore I fixed all entries I could find which were not following this
rule.
Also, I fixed parameters names in functions prototypes (in headers
files) which were not matching their definition.
Unfortunately, gda-log.h contains prototypes for functions which are not
yet implemented. So their entries in the API reference are still
empty. Maybe would it be better to comment prototypes while their
implementation is not provided yet?
Also, I updated a bit class titles in the TOC, removing final dots (if
any) and adding missing titles. To do it I modified doc/C/tmpl/*.sgml
files, I don't know if it's the correct way to do this, since I'm not
yet very familiar with gtk-doc.
I tested everything locally, and it seems great.
Since the patch is a quite big (~4000 lines), I compressed it with gzip.
Hope you will like it. I'm ready to do some modifications if needed.
Cheers,
--
{ "Laurent" => "http://lrz.samika.net"; }
Attachment:
api-reference.patch.gz
Description: GNU Zip compressed data