info.michael-simons.eu

Here’s a quick post to get the week started: Recently I was working on my arc42 example project, enforcing Sun / Oracle coding conventions through Checkstyle and it bugged me that my project was missing several package-info.java files.

While adding them and writing something useful I was happy that I chose good slices that fit exactly my building blocks.

As I was pretty much duplicating the docs, I tried to get the JavaDoc into my AsciiDoc documentation.

Including other files and parts of other files in AsciiDoc is easy, see include directive:

==== bikes (Blackbox)
 
Intent/Responsibility::
 
include::../main/java/ac/simons/biking2/bikes/package-info.java[tags=intent]

(see 05_building_block_view.adoc)

That means: go to package-info.java and get all the text between “tag::intent[]” and “end::intent[]”.

What I was struggling with was to come up with a formatting of the JavaDoc that works well in JavaDoc and in AsciiDoc. This is my solution:

/**
 <!-- tag::intent[] -->
   `bikes` provides the external API for reading, creating and manipulating
   bikes and their milages as well as computing statistics and generating charts.
 <!-- end::intent[] -->
 */
package ac.simons.biking2.bikes;

(see package-info.java)

That results in:

and

Well, I think that AsciiDoc is indeed a pretty good way to write technical documentation, though I still am more fluent in Markdown. I’m using the AsciiDoctor Maven plugin for my projects, Ralf has a nice blog post published today that helps you getting started with AsciiDoc using Gradle: Simple AsciiDoc Build with Gradle.