Javadoc reuse predefined text

Question

Is it possible somehow to create something like:

/** #define COMMON_NOTE_1="This note I want to re-use in several places" */
int varA; /** variable A (COMMON_NOTE_1) */
int varB; /** variable B (COMMON_NOTE_1) */

Some suggested 3 years ago it may not been possible do you know if it is possible in modern age?

If still not possible, there were suggestions to use C preprocessor. Any idea if C preprocessor can be integrated with IntelliJ? Or I would be happy also with python script automatically executed before compilation. I know Intelli J can be configured to run Ant before compilation. If ready made solution I would take it as well. But I do not want to write/modify ant script myself.

Answer 1

So I did find one ugly and limited way. But the best thing so far anyway. Lot better than previously proposed DUMMY variables. The major ugliness of DUMMY variables is that there would be DUMMY variables in your class and in your documentation. And even when you swallow messy DUMMY variables in your code you won't see "Note" directly but only link to it.

The better approach would be to use tag @value. First create ugly class like DocCommon where all notes will be hidden. eg.:

public class DocCommon {
    public static final String note1 = "Note: This is common note";
    public static final String note2 = "Note: This is common note2";
}

The you link it from anywhere like :

/** A: {@value com.whoever.DocCommon#note1} B*/

It will then shows in documentation directly like this:

A: "Note: This is common note" B

The disadvantage is that it will show with quotation marks " ". Another disadvantage is that it won't accept any HTML tags. Eg. when you put <br> it would throw error during javadoc compiling. So this wont work:

public static final String note1 = "Note: <br> This is common note";

Anyone has any better proposal? I noticed there might be other documentation tools than Javadoc. Any hint about particular one supporting multiline #defines?

Answer 2

You can do as follows:

/** This note I want to re-use in several places */
static final int DUMMY;
...

/** variable A see {@link #DUMMY COMMON_NOTE}. */
int varA; 
/** variable B see {@link #DUMMY COMMON_NOTE}. */
int varB; /** variable B (COMMON_NOTE_1) */

This creates a link in the documentation that when pressed will lead to the common doc. It won't show it inline though. Also depending on how long the common note is this might take more writing than duplicating the note, but it will be easier to maintain.