Documentation maintenance is one of the main goals of this documentation system. In the case of Java you may already use strings to explain certain concepts of your system. Instead of copy-and-pasting text between sources, you can refer to it inside your documentation. Text bellow is extracted from top class level JavaDoc /** * 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 * {@link Diversity} */ 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 } } :include-java-doc: HelloWorld.java JavaDoc Top level conceptual description of a problem. To avoid copy & paste of the content consider to re-use information. CustomDomain

Method level text can be referred to as well by specifying the parameter. Text bellow is extracted from method JavaDoc entry :include-java-doc: HelloWorld.java {entry: "sampleMethod"} sampleMethod 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

Use to disambiguate a field or a method name NestedName.entityName class HelloWorld { private int importantScore; public static class Nested { /** * system caclulates <b>importance</b> score based on following factors... */ private int importantScore; } } :include-java-doc: HelloWorldWithInner.java {entry: "Nested.importantScore"} system caclulates importance score based on following factors...

Links defined with are automatically converted to Inlined Code and become . To turn into a link you need to use Code References. Use the value to associate with the documentation link: Top level conceptual description of a problem. To avoid copy & paste of the content consider to re-use information. CustomDomain Alternatively you can define Global References to turn into a link. {@link MyClass} MyClass MyClass referencesPath {@link CustomDomain} 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 MyClass

Use the parameter to specify a title. :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 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 Code References file to link method parameters to reference pages. To do that, define references in a CSV file, using a two column format: . Parameters are now linked with a reference section for the documentation. 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

Use to enumerate entries of a enum from a file. You can exclude deprecated entries from the list by setting the parameter. Use the parameter to specify a title. include-java-enum-entries 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 excludeDeprecated :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 title :include-java-enum-entries: TransactionTypes.java {title: "Transaction Types"} BUY buy intrument SELL sell instrument

Use a Code References file to link enum entries to reference pages. To do that, define references in a CSV file, using a two column format: . 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 Global References. 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

Pass parameter to the plugins to treat JavaDoc content as markdown markdown: true /** * Top level **conceptual** description of a `CustomDomain` problem. * * markdown *list* * * item two * ``` * code snippet * goes here * ``` */ class HelloWorld { } :include-java-doc: HelloWorld.java {markdown: true} Top level conceptual description of a problem. markdown list item two CustomDomain code snippet goes here