On Sat, May 11, 2013 at 9:13 AM, Nick Wellnhofer <[email protected]> wrote:
> 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.
I have misgivings about individual methods (e.g. `CB_Nip_One` is a lousy name,
can't we do better?), but since major changes are coming down the pipe anyway
(e.g. introducing immutable String), who's gonna nitpick?
On one hand, without making all that functionality public, the C library would
be basically unusable -- so there's really only one choice open to us. On the
other hand, the design is not finished, so those APIs, despite being "public",
are not permanent. This project has a history of being pretty conservative
about public APIs, to the point where we've probably frightened a lot of
potential users off with big scary warnings over the years. Declaring an
unstable interface "public" feels strange -- but supposedly it's the kind of
thing which has worked for other Apache projects.
http://s.apache.org/hZ
Anyway, it's a design pattern: "good ideas and bad code build
communities, the other three combinations do not".
> 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.
Providing documentation in multiple languages is a hard problem. Replacing
here-docs with something more elegant seems less pressing to me than dealing
with things like creating links which work across multiple documentation
systems.
> 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
Yes, without such an overview, people would be lost.
Experience has shown that the uppercase/lowercase thing is a horrible trap,
though -- that really needs to be fixed (by hiding the implementing function),
not just explained.
> 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.
I wouldn't want to block the release because we haven't dealt with the
Markdown transition yet. It's not really straight-up Markdown either -- at
the least it's a custom Markdown extension which supports @tags and funky
links.
We can hack in individual features as short term fixes rather than solving all
these problems and integrating a parser as a dependencey. For instance, we
can replace the <code></code> construct with backticks. Detecting
markdown-style links and hacking in our own treatment wouldn't be much harder.
> 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.
FWIW... In this day and age, the HTML is probably going to get read a lot more
often.
Marvin Humphrey
