kaitai-io / kaitai_struct_java_runtime

Kaitai Struct: runtime for Java
MIT License
42 stars 18 forks source link

[...]/ByteBufferKaitaiStream.java:87: error: unknown tag: implNote #17

Closed ams-tschoening closed 5 years ago

ams-tschoening commented 5 years ago

Building the runtime using mvn package an JDK 8 fails for me because the non-standard Javadoc-tag @implNote is used. I get the following error:

    [exec] [ERROR] Failed to execute goal org.apache.maven.plugins:maven-javadoc-plugin:2.9.1:jar (attach-javadocs) on project kaitai-struct-runtime: MavenReportException: Error while creating archive:
    [exec] [ERROR] Exit code: 1 - C:\Users\tschoening\Documents\Eclipse\Java Sm-Mtg Bug 2543\Libs Java 3rd\Parsers\Generators\kaitai_struct\runtime\ams_bug_2543\src\src\main\java\io\kaitai\struct\ByteBufferKaitaiStream.java:87: error: unknown tag: implNote
    [exec] [ERROR]      * @implNote Unfortunately, there is no simple way to close memory-mapped ByteBuffer in
    [exec] [ERROR]        ^
    [exec] [ERROR]
    [exec] [ERROR] Command line was: "C:\Program Files\Java\jdk1.8\jre\..\bin\javadoc.exe" @options @packages
    [exec] [ERROR]
    [exec] [ERROR] Refer to the generated Javadoc files in 'C:\Users\tschoening\Documents\Eclipse\Java Sm-Mtg Bug 2543\Libs Java 3rd\Parsers\Generators\kaitai_struct\runtime\ams_bug_2543\src\target\apidocs' dir.
    [exec] [ERROR]
    [exec] [ERROR] -> [Help 1]
    [exec] [ERROR]
    [exec] [ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
    [exec] [ERROR] Re-run Maven using the -X switch to enable full debug logging.
    [exec] [ERROR]
    [exec] [ERROR] For more information about the errors and possible solutions, please read the following articles:
    [exec] [ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/MojoExecutionException
    [exec] Executed command resulted in error: "mvn" "package"; 1 at C:/max-x/perl/stmodul/amsoft_build/Libs/Java3rd/Exec.pm line 91.
    [exec] Result: 2

Non-standard because of the following:

There are no plans to attempt to popularize these particular tags outside of use by JDK documentation.

https://blog.codefx.org/java/new-javadoc-tags/#Current-Status

There's a workaround for the javadoc-plugin for Maven which works if I adopt your pom.xml, but that has a drawback:

By default all new tags are added to the end of the generated doc, which puts them below, e.g., @param and @return. To change this, all tags have to be listed in the desired order, so you have to add the known tags to the list below the three above:[...]

https://blog.codefx.org/java/new-javadoc-tags/#Command-Line

So, how do you want to handle this, by removing the tag or adopting pom.xml? And if the latter, how? Add all "new" tags or only the used one, care about their order...?

GreyCat commented 5 years ago

The solution you've proposed seems to a good middle ground. Thanks!