Hello...I am still trying to wrap my head round Asciidoctor. Can AsciiDoc be used to parse written code say in Java...and get an API style document?
|
I've had to go through this process recently myself. The answer is no. AsciiDoc (or AsciiDoctor) is a means to create documentation similar to what people did when text formatters existed before GUI editors. Markup indicators are embedded as plain text in the plain text documentation. To avoid the plain text from being interpreted as markup, certain conventions must be adhered to.
AsciiDoc can be used to embed API documentation in source code as comment blocks, but a third party tool or filter must be used to extract it. For a program to auto-generate API documentation, it must be language aware. So, Doxygen is often used for such processing. There have been some efforts with regard to the integration of AsciiDoc with DoxyGen, and Adres posted a question about integration of AsciiDoctor earlier this year (http://discuss.asciidoctor.org/Doxigen-support-td1359.html). Personally, I am waiting for the documentation on AsciiDoctor filters to be completed, as I'd like to build an integrated Perl filter into AsciiDoctor to replace POD or using Doxygen. Thanks, -Shaun |
Administrator
|
Excellent response Shaun! That's spot on. Note that if you want to write AsciiDoc in your Javadoc (Java docstrings), you can use Asciidoclet (see http://asciidoctor.org/news/2014/09/09/asciidoclet-1.5.0-released/). If you want to parse your Java code into an AST (abstract syntax tree, aka document tree), then you should use a program like Roaster (see https://github.com/forge/roaster). Roaster is a library for parsing the Java syntax. For those interested in how Asciidoctor and Roaster could be used together, think about how Roaster could be used to allow Java source to be included into a listing block based on it's *structure* instead of by line numbers or tagged regions. I think this would be an *awesome* extension for Asciidoctor (or AsciidoctorJ). Perhaps some work is already being done on it. Cheers, -Dan On Fri, Aug 22, 2014 at 1:59 PM, 5haun [via Asciidoctor :: Discussion] <[hidden email]> wrote: I've had to go through this process recently myself. The answer is no. AsciiDoc (or AsciiDoctor) is a means to create documentation similar to what people did when text formatters existed before GUI editors. Markup indicators are embedded as plain text in the plain text documentation. To avoid the plain text from being interpreted as markup, certain conventions must be adhered to. Dan Allen | http://google.com/profiles/dan.j.allen |
Free forum by Nabble | Edit this page |