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
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]
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;
That results in:
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.