Hello lucy-dev,
For the C library documentation, I decided to generate man pages from Lucy's
"DocuComments". For every public class, a man page with the following contents
is created:
* Name and abstract
* Description
* Public functions
* Public methods
* Abstract methods
* Novel methods
* Methods inherited from superclasses
* Inheritance info
To see how it looks, pull from master, change into the 'c' directory, build the
library, and run:
$ man -M autogen/man lucy_SegReader
There are some more classes, methods, and constructors which I think should be
made public to be included in the documentation. See branch 'clownfish-public'
for my suggestions.
The synopsis sections are still missing. The Perl bindings currently use
here-docs for the synopses in the code in perl/buildlib/Lucy/Build/Binding.pm
which I consider a bit ugly. I think we could benefit from a system that stores
additional documentation sections for different host languages in extra files.
But for the beginning, it might be enough to include some example C code
derived from the test suite.
It would also be nice to have a high-level overview of how to use Clownfish
classes from C. I don't mean how to create your own classes but simple stuff
like:
* Calling methods and functions (uppercase vs. lowercase)
* Memory management
* INCREF/DECREF
* incremented return values
* decremented arguments
* Short name macros
Another thing that has to be done for the man pages is to handle markup in
DocuComments. AFAICS, we currently use POD-style links and XML-style
<code></code> markup. I remember there was some discussion to switch to
Markdown. It might be a good time to revisit this.
When I'm finished with the man pages, I plan to use a man-to-html converter and
put the result on the Lucy website.
Nick
