Greets,
The POD documentation that Perl users of Lucy see is mostly autogenerated
from "DocuComments" in our cfh files. DocuComments probably look a lot
like Javadocs to most observers, though there are many similar
documentation systems out there[1].
Much of Lucy's documentation was originally written in POD, and there are
still some legacy POD-isms here and there, especially POD-style
L<links|perlpod>. Mixing POD and C-style comments is awkard, though; we
should really find a better syntax for those. Also, for inline code
snippets, we currently support XML-style <code>code tags</code>. I think
it would be a mistake to continue the transition to XML-style, a la C#.
Conceptually, the option I find most attractive is integrating Markdown
with Javadoc-style @tags, which has been done more than once:
http://www.stack.nl/~dimitri/doxygen/markdown.html
http://code.google.com/p/markdown-doclet/wiki/Examples
Honorable mention goes to Scaladoc, which mixes @tags with Trac-style wiki
markup.
https://wiki.scala-lang.org/display/SW/Syntax
None of those products would work for Clownfish as a direct dependency,
though. Doxygen has its advantages, but it's huge, it's GPL, its
generated HTML is funky, it's completely baffled by our autogenerated C
code, and its Markdown integration is idiosyncratic -- in short, I don't
think it's in Clownfish's interest to lash itself to Doxygen.
Instead, I think it might make sense to work with the C library Sundown:
https://github.com/tanoku/sundown
At first look, Sundown seems appropriate as a dependency for us:
cross-platform, no configuration, just a handful of .c and .h files.
Here's an approach I hope will work well:
1. Extract comment text from .cfh file.
2. Remove C comment artifacts and make content flush left.
3. Preprocess select @tags, converting them into an intermediate
Markdown format. At this point, the transformation of the original
comment into pure Markdown is complete.
4. Parse intermediate Markdown with Sundown.
5. Use Sundown plus custom plugins to render content in host-specific
output formats, e.g. POD, Rdoc.
Committing to Markdown as Clownfish's documentation language also gives us
the option of writing docs as pure .mdtext files.
Thoughts?
Marvin Humphrey
[1] http://www.stack.nl/~dimitri/doxygen/links.html
