[SIS-565] Remove @module and @preformat taglets

• Type: Task
• Status: Closed
• Priority: Minor
• Resolution: Fixed
• Fix Version/s: 1.4
• Component/s: Build process, Documentation
• Assignee: Martin Desruisseaux
• Reporter: Martin Desruisseaux
• Created: 28/Dec/22 13:31
• Updated: 28/Dec/22 16:45
• Resolved: 28/Dec/22 16:38

Description

SIS uses a custom doclet provided in the sis-build-helper Maven artifact. This doclet provides 3 tags:

• @module for telling which module contains a class.
• @preformat for code snippet.
• @include for inserting an HTML fragment defined in an external file. Used for MathML.

The @module tag can be fully removed because Jigsaw modularisation will provide this information. The @preformat tag can be replaced by the new @snippet standard Javadoc tag introduced in Java 18. We will lost syntax coloration, but there is more benefits to win, in particular the fact that the standard tag will be (hopefully) be recognized by IDE.

The use of @snippet requires Java 18 or later for building SIS, but the compilation result is still compatible with Java 11.

Reference: Programmer's Guide to Snippets.

Issue Links

• Is contained by: SIS-561 Upgrade to Java 11