This generator is discontinued. The recommended practice is to use Jamal doclet along with snippet handling and other Jamal tools instead. For more information see https://github.com/verhas/jamal
Jdocify is a simple generator that helps you to keep Javadoc up-to-date.
Sometimes it happens that you want to use the values of some fields in the JavaDoc documentation. For example the documentation of License3j contains the following JavaDoc fragment:
* <li>Add the digest algorithm string to the license as a feature. The feature name is
* {@code signatureDigest} (name is defined in the constant {@link #DIGEST_KEY} in this
* class).</li>It may happen that during the lifetime of the code the value defined in the variable DIGEST_KEY gets changed from signatureDigest to digestKey.
(Just because why not.)
Unless the developer performing the maintenance does a thorough search the JavaDoc becomes outdated.
Jdocify automatize the update of the JavaDoc. The JavaDoc has to be extended with a HTML comment of the form
<!--CODE FINAL_STATIC_FIELD_NAME-->
like in the following sample:
* <li>Add the digest algorithm string to the license as a feature. The feature name is <!--CODE
* DIGEST_KEY-->{@code signatureDigest} (name is defined in the constant {@link #DIGEST_KEY} in this
* class).</li>When Jdocify processes the file it checks that the {@code …} after the
<!--CODE DIGEST_KEY-->
is the same as the value of the static final field DIGEST_KEY and in case it is different it updates the {@code …} in the JavaDoc.
Another feature is, when you have some text repeated in the JavaDoc. In that case you can write
//DEFINE THIS=The method returns {@code this} to help method chaining.
which kind of defines the symbol THIS to be that sentence.
After that you can use in JavaDoc
@returns <!--THIS-->The method returns {@code this} to help method chaining.<!--/-->
instead of just writing the sentence. It is a bit longer but the actual text is maintained by JDocify. If you just happen to write
@returns <!--THIS--><!--/-->
or you edit and modify the text after the
//DEFINE THIS=The method returns a clone of {@code this} to help method chaining.
(note that the text is now changed) then Jdocify insert the current text between the
<!--THIS-->
and
<!--/-->
maintaining the text and keeping it consistent. You do not need to change the sentence in the JavaDoc of each and every chained method. Jdocify does it.
The full form of the HTML comment used for the CODE purpose is:
<!--CODE fieldName template string -->
if the template string is missing, as in the example in the introduction, then the value will be used by itself. If there is a template then the name of the field in the template will be replaced with the value of the field. For example:
final static String FIELD = "fieldValue";
<!--CODE FIELD ${FIELD}-->{@code ${fieldValue}}
You can also use { and } characters in the template, but they have to be balanced.
The DEFINE definition of a text has to precede the use.
The definition is always in a comment that starts with // characters and there should be no space between the // and the word DEFINE.
The name of the variable has to be all capital letters A-Z, 0-9 and the _ underscore character, and it should not start with a number (as usual constant names in Java).
When the text is used the defined variable name has to be in an HTML comment, like
<!--VARIABLE_NAME-->
without any spaces. The end of the text is marked by the HTML comment
<!--/-->
What is between will be updated with the actual text as it was defined in the //DEFINE… comment.
The scope of a //DEFINE is within a single source file.
You can configure the boolean parameter
processAllClasses
to control if the generator should do its work on all classes or onlyon those that are annotated with the @Jdocify annotation.
The default is false, which means that you have to annotate the classes that need the service of the generator.