On Thu, Aug 6, 2015 at 12:56 PM, Nick Wellnhofer <[email protected]> wrote: > Standalone Markdown documentation files are now converted to HTML for the C > API documentation. The doc generator has also been updated to only include > code blocks matching the host language. This makes it possible to have a > single Markdown source file with code blocks for multiple languages > > https://raw.githubusercontent.com/apache/lucy/master/core/Lucy/Docs/Tutorial/SimpleTutorial.md
Fantastic! Tons of work paying off... > being converted to Perl POD > > https://github.com/nwellnhof/lucy/blob/generated_docs/perl/lib/Lucy/Docs/Tutorial/SimpleTutorial.pod > > and C HTML > > https://rawgit.com/nwellnhof/lucy/generated_docs/c/autogen/share/doc/clownfish/Lucy/Docs/Tutorial/SimpleTutorial.html The generated HTML looks very attractive. :) Some aspects of the tutorial will need to be rejiggered to work across multiple languages -- e.g. `indexer.pl` needs to become `indexer` or something like that. > The full C documentation in its current state is here for review: > > https://rawgit.com/nwellnhof/lucy/generated_docs/c/autogen/share/doc/clownfish/lucy.html One thing I noticed is that the lower case prefix is being used for method call invocations: `lucy_Analyzer_Transform`. (It's very nice having those prefixes "screened back" to a lighter color... I know it's been that way for a while, but it's worth saying again...) I plan to give our generated docs a complete review before we publish 0.5.0. > I'd like to move forward by exposing public methods in the Perl docs > automatically. For Lucy, I think it's best to remove the "public" specifier > from methods that are undocumented in the Perl bindings. Then we can > selectively readd a couple of methods. That seems like a good plan. The autogenerated bindings are not always ideal. To cite an example from the Clownfish Go bindings, the default type mapping for `cfish_Vector*` is `[]interface{}`, so that's what the hash.Keys() returned. I overrode that to return `[]string`, since we know that the Vector will always be a Vector of strings. (A future Clownfish improvement would be to support `Vector<String>`). Marvin Humphrey
