[jira] [Updated] (SIS-565) Remove @module and @preformat taglets

["Martin Desruisseaux (Jira)" <ji...@apache.org>]

     [ https://issues.apache.org/jira/browse/SIS-565?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Martin Desruisseaux updated SIS-565:
------------------------------------
    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|https://docs.oracle.com/en/java/javase/19/code-snippet/index.html].


  was:
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.

Reference: [Programmer's Guide to Snippets|https://docs.oracle.com/en/java/javase/19/code-snippet/index.html].



> Remove @module and @preformat taglets
> -------------------------------------
>
>                 Key: SIS-565
>                 URL: https://issues.apache.org/jira/browse/SIS-565
>             Project: Spatial Information Systems
>          Issue Type: Task
>          Components: Build process, Documentation
>            Reporter: Martin Desruisseaux
>            Assignee: Martin Desruisseaux
>            Priority: Minor
>             Fix For: 1.4
>
>
> 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|https://docs.oracle.com/en/java/javase/19/code-snippet/index.html].



--
This message was sent by Atlassian Jira
(v8.20.10#820010)