Documentation maintenance is one of the main goals of this documentation system. In the case of Java you may already use JavaDoc strings to explain certain concepts of your system. /** * Top level conceptual description of a {@link CustomDomain} problem. * <p> * To avoid <b>copy & paste</b> of the content consider to re-use information. */ class HelloWorld { /** * Each year we hire students from different universities to increase * <code>diversity</code> */ private int numberOfStudents; /** * Conceptual description of a <i>Domain</i> problem. * <p> * It will work only if you put high level description here and * <b>not</b> implementation details. * * @param p1 important parameter of something * @param p2 sample <i>offset</i> according to the rules of the universe * @return name of the <b>best</b> sample */ public String sampleMethod(String p1, int p2) { validate(); process(p2); // important comment notifyAll(p1); // very important return bestSample(); } public void sampleMethod(Map<String, Integer> p1, int p2, boolean isActive) { // overloaded method } /** * @param trader trader that performs action * @param transaction transaction to perform action on */ public void importantAction(Trader trader, Transaction transaction) { // TODO important } public Data createData() { // create data } } Instead of copy-and-pasting text between sources, you can refer to it inside your documentation. :include-java-doc: HelloWorld.java Text bellow is extracted from top class level JavaDoc Top level conceptual description of a CustomDomain problem. To avoid copy & paste of the content consider to re-use information.

Method level JavaDoc text can be referred to as well by specifying the entry parameter. :include-java-doc: HelloWorld.java {entry: "sampleMethod"} Text bellow is extracted from sampleMethod method JavaDoc Conceptual description of a Domain problem. It will work only if you put high level description here and not implementation details.

:include-java-doc: HelloWorld.java {entry: "numberOfStudents"} Each year we hire students from different universities to increase diversity

Links defined with {@link MyClass} are automatically converted to snippets/inlined-code-snippets Inlined Code and become MyClass . To turn MyClass into a link you need to use snippets/code-references Code References.Use the referencesPath value to associate {@link CustomDomain} with the documentation link: CustomDomain, example-references/domain Trader, example-references/domain#trader Transaction, example-references/domain#transaction BUY, example-references/domain#transaction-buy SELL, example-references/domain#transaction-sell Alternatively you can define snippets/code-references#global-references Global References to turn MyClass into a link.

:include-java-doc-params: HelloWorld.java {entry: "sampleMethod"} p1 String important parameter of something p2 int sample <i>offset</i> according to the rules of the universe return String name of the <b>best</b> sample Use the title parameter to specify a title. :include-java-doc-params: HelloWorld.java {entry: "importantAction", title: "Trading Required Parameters"} trader Trader trader that performs action transaction Transaction transaction to perform action on

Use the snippets/code-references Code References file to link method parameters to reference pages.To do that, define references in a CSV file, using a two column format: type-or-variable-name, link . CustomDomain, example-references/domain Trader, example-references/domain#trader Transaction, example-references/domain#transaction BUY, example-references/domain#transaction-buy SELL, example-references/domain#transaction-sell :include-java-doc-params: HelloWorld.java { entry: "importantAction", title: "Trading Required Parameters", referencesPath: "references/javadoc-references-demo.csv"} trader Trader trader that performs action transaction Transaction transaction to perform action on Parameters are now linked with a reference section for the documentation.

Use include-java-enum-entries to enumerate entries of a enum from a file. package my.company; enum MyEnum { /** * description of <b>entry one</b> */ ENTRY_ONE, /** * description of entry two * <ul> * <li>item one</li> * <li>item two</li> * </ul> */ ENTRY_TWO, /** * Don't use, instead use ENTRY_TWO */ @Deprecated ENTRY_THREE } :include-java-enum-entries: MyEnum.java ENTRY_ONE description of <b>entry one</b> ENTRY_TWO description of entry two <ul> <li>item one</li> <li>item two</li> </ul> ENTRY_THREE Don't use, instead use ENTRY_TWO You can exclude deprecated entries from the list by setting the excludeDeprecated parameter. :include-java-enum-entries: MyEnum.java {excludeDeprecated: true} ENTRY_ONE description of <b>entry one</b> ENTRY_TWO description of entry two <ul> <li>item one</li> <li>item two</li> </ul> ENTRY_THREE Don't use, instead use ENTRY_TWO Use the title parameter to specify a title. :include-java-enum-entries: TransactionTypes.java {title: "Transaction Types"} BUY buy intrument SELL sell instrument

Use a snippets/code-references Code References file to link enum entries to reference pages.To do that, define references in a CSV file, using a two column format: enum-name, link . CustomDomain, example-references/domain Trader, example-references/domain#trader Transaction, example-references/domain#transaction BUY, example-references/domain#transaction-buy SELL, example-references/domain#transaction-sell package my.company; enum TransactionTypes { /** * buy intrument */ BUY, /** * sell instrument */ SELL } :include-java-enum-entries: TransactionTypes.java { title: "Transaction Types", referencesPath: "references/javadoc-references-demo.csv" } BUY buy intrument SELL sell instrument Enums are now linked with a reference section for the documentation.Note: you can reuse the same CSV file for Enums, Parameters, Code Snippets. Alternatively, you can use snippets/code-references#global-references Global References.