arc42 documentation: Building block intent from JavaDoc

Deduplicate documentation when using AsiiDoc
July 11, 2016 by Michael

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 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)

(see 05_building_block_view.adoc)

That means: go to 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;


That results in:

JavaDoc result


AsciiDoc result

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.

No comments yet

Post a Comment

Your email is never published. We need your name and email address only for verifying a legitimate comment. For more information, a copy of your saved data or a request to delete any data under this address, please send a short notice to from the address you used to comment on this entry.
By entering and submitting a comment, wether with or without name or email address, you'll agree that all data you have entered including your IP address will be checked and stored for a limited time by Automattic Inc., 60 29th Street #343, San Francisco, CA 94110-4929, USA. only for the purpose of avoiding spam. You can deny further storage of your data by sending an email to, with subject “Deletion of Data stored by Akismet”.
Required fields are marked *