Docstract-0.2.0 Released.

Docstract is an small java project which reads a java source file, extracts the comments between /** and */ sequentially from all over the file and stores them inside an output AsciiDoc file. The idea is not new in fact it is from https://github.com/javaee-samples/javaee7-samples/ developed by Aslak Knutsen but instead of using Ruby and inside Awestruct, this project is written in java and it is run from CLI.

Let me show you an example to understand what this application does:

This is a class which contains some comments to be processed.

And the output document looks like:

Note that in comments we are also using include macro for inserting files inside. The rules for inclusion are the next ones:

• if include contains a java file, like first example, the whole class is read and inserted within AsciiDoc source code blocks.
• if include contains a java file but with # symbol, like second one, the right part of # will be used as method name of given class. So for example Project#setId(String, String) will include a method of Project's class called setId and receiving two string parameters.
• if include contains an xml file, the file is inserted "as is" within AsciiDoc source code block.
• if include contains an xml file and between brackets there is an xpath expression, the result of that expression will be inserted.
• any other include is left "as is", so it will be processed by AsciiDoc(tor) processor.

Also note that the include files will be resolved relative from place where the CLI is being run, typically from the root of the project.

You can use callouts inside java and xml code and the processor will render it in the proper way.

In java you can write a callout as a single line comment with callout number between <, > at start.

In xml you can write callouts between +xml+ comments and the callout number being the first word.

You can grab a runnable jar from https://bintray.com/lordofthejars/generic/Docstract/0.2.0/view/files

To render previous class we can call as:

java -jar docstract-<version>.jar --input=src/test/java/com/lordofthejars/asciidoctorfy/MM.java --output=README.adoc

And an AsciiDoc file will be generated from comments blocks.

There is one optional parameter called --baseDir. This parameter is used to set the baseDir in include macros. So for example if you set baseDir to /home/lotj/project, the include macro will be resolved to include::/home/lotj/project/src/test/java/....

You can see an example at community Tomitribe examples with class: https://github.com/tomitribe/community/blob/master/mongodb-example/src/test/java/org/superbiz/nosql/mongodb/GreetingsSessionBeanTest.java and the rendered output: https://github.com/tomitribe/community/blob/master/mongodb-example/README.adoc.

New features will be added when they are required but of course feel free to clone and improve it.

Project Site: https://github.com/lordofthejars/docstract

We Keep Learning,
Alex.

Weiß mit dem Locken umzugehn, Und mich auf's Pfeifen zu verstehn. Drum kann ich froh und lustig sein, Denn alle Vögel sind ja mein. (Die Zauberflöte - Wolfgang Amadeus Mozart)

Music: https://www.youtube.com/watch?v=PRtvVQ1fq8s