On Sun, Nov 23, 2014 at 10:05 AM, Nick Wellnhofer <[email protected]> wrote: > I made the necessary changes for both Lucy and Clownfish in the `markdown` > branches. Man pages and HTML documentation for the C bindings, as well as > Perl POD are now autogenerated from Markdown DocuComments.
It's really cool to see this implemented, Nick! > I also uploaded a sample of the new HTML documentation for the C APIs: > > http://lucy.apache.org/docs/c/ > http://lucy.apache.org/docs/c/cfish.html > http://lucy.apache.org/docs/c/lucy.html The HTML looks spiffy! The W3C validator reports a few problems with some of the generated HTML -- it might be nice to clean those up. > C API docs are only generated for public classes. Since not all classes are > marked public yet, some pages are missing and some links are dead. To be honest, I'm not thrilled with what we're putting out there as the public API for either Clownfish or Lucy -- there are a number of things marked "public" which really shouldn't be. The subset of the API published in the Perl docs is what I would consider canonical. However, I'm not going to harp on this issue until after I've made substantial progress on the higher priority of adding host languages. > The Markdown documentation supports links to classes with a custom > `clownfish` URI scheme. A link like > > [RegexTokenizer](clownfish:class:lucy:RegexTokenizer) > > will be automatically converted to point to right location depending on the > host language. This can also be (ab)used for other language-dependent stuff. I think this is a reasonable extension. Question: does CommonMark support conditional inclusion of code blocks? It would be nice to put things such as the Lucy tutorial into core, but providing host-specific code samples poses a challenge. Marvin Humphrey
