Ascii doctor and written code

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

Ascii doctor and written code

pkkamos
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? 
Reply | Threaded
Open this post in threaded view
|

Re: Ascii doctor and written code

5haun
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
Reply | Threaded
Open this post in threaded view
|

Re: Ascii doctor and written code

mojavelinux
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.

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


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Ascii-doctor-and-written-code-tp2034p2047.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--