Writing documentation with Asciidoc is such a treat. We can add markers to our code where we want to explain something in our code. The markers have numbers and are enclosed in < and > brackets. The explanation for the markers follows a code listing in a callout list. Here we use the same marker and add extra text to explain the code. We can put the markers in comments in our code so we can use the markers in existing code.
Suppose we have the following piece of documentation where we add two markers (in comments) to some Groovy source code:
[source,groovy]
----
package com.mrhaki.adoc
class Sample {
String username // <1>
String toString() {
"${username?.toUpperCase() ?: 'not-defined'}" // <2>
}
}
----
<1> Simple property definition where Groovy will generate the +setUsername+ and +getUsername+ methods.
<2> Return username in upper case if set, otherwise return +not-defined+.
When we generate this into an HTML document with the prettify syntax highlighter and icon font we get the following output:
