Class Level

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

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.

Field Level

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

Handling Links

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.

Method Params

: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

Method Params With References

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.

Enum Entries

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

Enum Entries With References

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.