jtulach / codesnippet4javadoc Goto Github PK
View Code? Open in Web Editor NEWJavadoc doclet to include real code snippets in the documentation
License: GNU General Public License v3.0
codesnippet4javadoc's People
Contributors
Stargazers
Watchers
codesnippet4javadoc's Issues
Larger snippets fail
@jtulach : nice tool 👍
I'm trying to use it in our open source project were we use an annotation processor to generate bean-mappings (MapStruct). The javadoc examples would include samples of the generated code.
I've copied those samples (api + generated code) to the test directory of the api project. When I use too long snippets, the javadoc processor fails: javadoc: error - Line is too long in: ../value/OrderMapperImpl.java
Javadoc:
/**
* Configures the mapping of source constant value to target constant value.
*
* {@codesnippet OrderMapperImpl}
*
*/Targeted source code
// BEGIN: OrderMapperImpl
public class OrderMapperImpl implements OrderMapper {
@Override
public ExternalOrderType orderTypeToExternalOrderType(OrderType orderType) {
if ( orderType == null ) {
return null;
}
ExternalOrderType externalOrderType_;
switch ( orderType ) {
case EXTRA: externalOrderType_ = ExternalOrderType.SPECIAL;
break;
case STANDARD: externalOrderType_ = ExternalOrderType.DEFAULT;
break;
case NORMAL: externalOrderType_ = ExternalOrderType.DEFAULT;
break;
case RETAIL: externalOrderType_ = ExternalOrderType.RETAIL;
break;
case B2B: externalOrderType_ = ExternalOrderType.B2B;
break;
default: throw new IllegalArgumentException( "Unexpected enum constant: " + orderType );
}
return externalOrderType_;
}
}
// FINISH: OrderMapperImplAny idea how to fix this:
CodesnippetDoclet does not work on JDK-21
CodesnippetDoclet crashes on JDK-21.
WARNING: stderr: java.lang.NoClassDefFoundError: com/sun/tools/javac/main/CommandLine
WARNING: stderr: at com.sun.tools.oldlets.javadoc.main.Start.parseAndExecute(Start.java:282)
WARNING: stderr: at com.sun.tools.oldlets.javadoc.main.Start.begin(Start.java:234)
WARNING: stderr: at com.sun.tools.oldlets.javadoc.main.Start.begin(Start.java:227)
WARNING: stderr: at org.apidesign.javadoc.codesnippet.Doclet.run(Doclet.java:430)
WARNING: stderr: at jdk.javadoc/jdk.javadoc.internal.tool.Start.parseAndExecute(Start.java:575)
WARNING: stderr: at jdk.javadoc/jdk.javadoc.internal.tool.Start.begin(Start.java:398)
WARNING: stderr: at jdk.javadoc/jdk.javadoc.internal.tool.Start.begin(Start.java:347)
WARNING: stderr: at jdk.javadoc/jdk.javadoc.internal.tool.Main.execute(Main.java:57)
WARNING: stderr: at jdk.javadoc/jdk.javadoc.internal.tool.Main.main(Main.java:46)
WARNING: stderr: Caused by: java.lang.ClassNotFoundException: com.sun.tools.javac.main.CommandLine
WARNING: stderr: at java.base/java.net.URLClassLoader.findClass(URLClassLoader.java:445)
WARNING: stderr: at java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:593)
WARNING: stderr: at java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:526)
WARNING: stderr: ... 9 more
WARNING: stderr: CodesnippetDoclet: error - fatal error
WARNING: stderr: error: an unknown error has occurred
WARNING: stderr: 1 error
Missing constructor in Log class causes NoSuchMethodError
Because of this change, I get the following error message when running this doclet under JDK 17:
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-javadoc-plugin:3.3.0:jar (attach-javadocs) on project test: MavenReportException: Error while generating Javadoc:
[ERROR] Exit code: 4 - error: fatal error encountered: java.lang.NoSuchMethodError: 'void com.sun.tools.javac.util.Log.<init>(com.sun.tools.javac.util.Context, java.io.PrintWriter, java.io.PrintWriter, java.io.PrintWriter)'
[ERROR] error: Please file a bug against the javadoc tool via the Java bug reporting page
[ERROR] (http://bugreport.java.com) after checking the Bug Database (http://bugs.java.com)
[ERROR] for duplicates. Include error messages and the following diagnostic in your report. Thank you.
[ERROR] java.lang.NoSuchMethodError: 'void com.sun.tools.javac.util.Log.<init>(com.sun.tools.javac.util.Context, java.io.PrintWriter, java.io.PrintWriter, java.io.PrintWriter)'
[ERROR] at com.sun.tools.oldlets.javadoc.main.Messager.<init>(Messager.java:121)
[ERROR] at com.sun.tools.oldlets.javadoc.main.Messager.<init>(Messager.java:105)
[ERROR] at com.sun.tools.oldlets.javadoc.main.Start.<init>(Start.java:128)
[ERROR] at com.sun.tools.oldlets.javadoc.main.Start.<init>(Start.java:122)
[ERROR] at com.sun.tools.oldlets.javadoc.main.Start.<init>(Start.java:138)
[ERROR] at org.apidesign.javadoc.codesnippet.Doclet.run(Doclet.java:393)
[ERROR] at jdk.javadoc/jdk.javadoc.internal.tool.Start.parseAndExecute(Start.java:556)
[ERROR] at jdk.javadoc/jdk.javadoc.internal.tool.Start.begin(Start.java:393)
[ERROR] at jdk.javadoc/jdk.javadoc.internal.tool.Start.begin(Start.java:342)
[ERROR] at jdk.javadoc/jdk.javadoc.internal.tool.Main.execute(Main.java:63)
[ERROR] at jdk.javadoc/jdk.javadoc.internal.tool.Main.main(Main.java:52)
Consider configuration flag to not @link to other classes
I believe our build fails because this doclet is creating Javadoc @link tags to link to other source files, and in some cases these other classes might not be on the classpath when the JavaDoc is generated. It would be useful to consider introducing some configuration flag to not do any linking in code snippets to other class files.
I can provide additional context in a follow-up comment, but I wanted to surface this to get initial impressions.
Hide some elements from Javadoc
It would be nice to have a way to hide @Deprecated or even other elements from the Javadoc.
CodeSnippet.txt
Java API Link Detection / Generation
Under JDK11, it does not correctly handle
<detectJavaApiLink>true</detectJavaApiLink>
and generates invalid links e.g.
https://docs.oracle.com/en/java/javase/11/docs/api/java/lang/Throwable.html
instead of
https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/Throwable.html
Its possible to reproduce by changing
diff --git a/testing/pom.xml b/testing/pom.xml
index f8e2f7a..7da4386 100644
--- a/testing/pom.xml
+++ b/testing/pom.xml
@@ -75,10 +75,11 @@
-header Header -bottom Bottom -group Extra org.apidesign.javadoc.testing:org.apidesign.javadoc ${testing.doclint}
</additionalOptions>
<failOnWarnings>true</failOnWarnings>
+ <detectJavaApiLink>true</detectJavaApiLink>
<links>
<!-- JDK 10 and above uses element-list link -->
<!-- https://docs.oracle.com/javase/10/docs/api/element-list is a downloadable file -->
- <link>https://docs.oracle.com/javase/10/docs/api/</link>
+ <!-- <link>https://docs.oracle.com/en/java/javase/11/docs/api/</link> -->
<!-- Reactor uses the older filename package-list -->
<!-- https://projectreactor.io/docs/core/release/api/package-list is a downloadable file -->
And using either an explicit link or detectJavaApiLink
javadoc: error - Cannot read ./java/com/foo/doc-files/network-icon.png Input length = 1
I have images imbedded into my javadocs with: <img src="doc-files/alert-diagram.png" alt="Alert diagram">. It worked fine.
I added codesnippet4javadoc with:
-doclet org.apidesign.javadoc.codesnippet.Doclet \
-docletpath codesnippet4javadoc/doclet/target/classes \
-maxLineLength 120 \
Now I get the following errors in the log:
Loading source file java/com/foo/Matic.java...
Constructing Javadoc information...
javadoc: error - Cannot read ./java/com/foo/doc-files/alert-diagram.png Input length = 1
javadoc: error - Cannot read ./java/com/foo/doc-files/alert-icon.png Input length = 1
javadoc: error - Cannot read ./java/com/foo/doc-files/data-storage-diagram.png Input length = 1
javadoc: error - Cannot read ./java/com/foo/doc-files/data-storage-icon.png Input length = 1
Standard Doclet version 1.8.0_60
Building tree for all the packages and classes...
Without the doclet, this doesn't happen.
The images are still in the javadoc, so this is a cosmetic issue.
My software versions:
codesnippet4javadoc: master (22728d5)
java version "1.8.0_60"
Java(TM) SE Runtime Environment (build 1.8.0_60-b27)
Java HotSpot(TM) 64-Bit Server VM (build 25.60-b23, mixed mode)
OS X 10.11
Doclet is suppressing the Javadoc Warnings and Errors
This doclet is suppressing the standard Javadoc warnings and errors.
Discovered this when I noticed Java 11 complained about some HTML tags that worked fine when we where using Java 8. We did not get them in the API where we are using this doclet, but got a lot of them in our application. I found this strange, so I disabled this doclet and I got the same warnings and errors in our API.
With this doclet configured I am not getting the javadoc warnings and errors.
Such like these:
error: tag not supported in the generated HTML version: tt
warning: no @return
warning: no @param for <C>
javadoc {
options.doclet = "org.apidesign.javadoc.codesnippet.Doclet"
options.docletpath = configurations.snippetdoclet.files.asType(List)
options.addStringOption "snippetpath", "src/test/java"
options.addStringOption "maxLineLength", "120"
options.addStringOption "Xmaxerrs", "400"
options.addStringOption "Xmaxwarns", "400"
options.addStringOption "--add-opens=jdk.javadoc/com.sun.tools.javadoc.main=ALL-UNNAMED"
}
Also with this doclet I cannot write short links in the JavaDoc.
warning - Tag @link: reference not found
Using this doclet it complains about @{link Class}, even though Class is on the imports, but the warning goes away when I use @{link com.company.Class}
Not using this doclet Javadoc does not complain about this short link.
No warning on missing @since in annotation types
In the following code the missing @since wasn't reported:
@Retention(RetentionPolicy.SOURCE)
public @interface MessageResolution {
/**
* The receiver object class that this message implementation belongs to.
*
* An annotation processor generates a {@link ForeignAccess} class, which the
* {@link TruffleObject} can use to implement {@link TruffleObject#getForeignAccess()}.
*
* @return class of the receiver object
*
* @since 0.13
*/
Class<?> receiverType();
}[Feature request] Support wildcards in -snippetpath args
When configuring aggregate javadocs using codesnippet4javadoc in a multi-module maven project, I have to enumerate every sub-module's source path containing the code snippets as -snippetpath arg.
For e.g.
<additionalOptions>
-snippetpath A/B/src/samples/java
-snippetpath C/D/src/samples/java
-snippetpath X/Y/src/samples/java
</additionalOptions>
It would be great if you can support wildcards to scan all sub-directories that match the regex.
Something like this:
<additionalOptions>-snippetpath **/src/samples/java</additionalOptions>
Codesnippet issues on JDK 13 and JDK 14
I've noticed issues with CodeSnippet 0.53 and 0.54 when running on JDK 13 and JDK 14. The issues are slightly different depending on the CodeSnippet version.
On CodeSnippet 0.53, with JDK 13 and 14, I see the following output in my build (which then fails as the build is set to fail on warning and errors):
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-javadoc-plugin:3.2.0:jar (attach-javadocs) on project azure-core: MavenReportException: Error while generating Javadoc:
[ERROR] Exit code: 1 - error: no class output directory specified
[ERROR] CodesnippetDoclet: warning - File ignored: "/Users/jonathan/Code/azure/forks/azure-sdk-for-java/sdk/core/azure-core/src/main/java/module-info.java" (not yet supported)
[ERROR] /Users/jonathan/Code/azure/forks/azure-sdk-for-java/sdk/core/azure-core/src/main/java/com/azure/core/credential/SimpleTokenCache.java:4: error: not in a module on the module source path
[ERROR] package com.azure.core.credential;(This list of classes carries on for every class in the module).
On CodeSnippet 0.54, with JDK 13 and 14, I see the following output in my build (which then fails):
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-javadoc-plugin:3.2.0:jar (attach-javadocs) on project azure-core: MavenReportException: Error while generating Javadoc:
[ERROR] Exit code: 1 - java.lang.IllegalStateException: Cannot call public void com.sun.tools.javac.main.Option.process(com.sun.tools.javac.main.OptionHelper,java.lang.String,java.lang.String) throws com.sun.tools.javac.main.Option$InvalidValueException with [com.sun.tools.oldlets.javadoc.main.Start$1@2cae1042, --patch-module, com.azure.core=/Users/jonathan/Code/azure/forks/azure-sdk-for-java/sdk/core/azure-core/src/main/java:/Users/jonathan/Code/azure/forks/azure-sdk-for-java/sdk/core/azure-core/target/generated-sources/annotations]
[ERROR] at com.sun.tools.oldlets.javadoc.main.SymbolKind.invokeOrNull(SymbolKind.java:345)
[ERROR] at com.sun.tools.oldlets.javadoc.main.ToolOption.processOption(ToolOption.java:463)
[ERROR] at com.sun.tools.oldlets.javadoc.main.ToolOption$23.process(ToolOption.java:210)
[ERROR] at com.sun.tools.oldlets.javadoc.main.Start.parseAndExecute(Start.java:311)
[ERROR] at com.sun.tools.oldlets.javadoc.main.Start.begin(Start.java:232)
[ERROR] at com.sun.tools.oldlets.javadoc.main.Start.begin(Start.java:225)
[ERROR] at org.apidesign.javadoc.codesnippet.Doclet.run(Doclet.java:392)
[ERROR] at jdk.javadoc/jdk.javadoc.internal.tool.Start.parseAndExecute(Start.java:552)
[ERROR] at jdk.javadoc/jdk.javadoc.internal.tool.Start.begin(Start.java:396)
[ERROR] at jdk.javadoc/jdk.javadoc.internal.tool.Start.begin(Start.java:342)
[ERROR] at jdk.javadoc/jdk.javadoc.internal.tool.Main.execute(Main.java:63)
[ERROR] at jdk.javadoc/jdk.javadoc.internal.tool.Main.main(Main.java:52)
[ERROR] Caused by: java.lang.reflect.InvocationTargetException
[ERROR] at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
[ERROR] at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
[ERROR] at java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
[ERROR] at java.base/java.lang.reflect.Method.invoke(Method.java:564)
[ERROR] at com.sun.tools.oldlets.javadoc.main.SymbolKind.invokeOrNull(SymbolKind.java:343)
[ERROR] ... 11 more
[ERROR] Caused by: java.lang.IllegalArgumentException
[ERROR] at jdk.compiler/com.sun.tools.javac.main.OptionHelper$GrumpyHelper.handleFileManagerOption(OptionHelper.java:139)
[ERROR] at jdk.compiler/com.sun.tools.javac.main.Option.process(Option.java:1205)
[ERROR] at jdk.compiler/com.sun.tools.javac.main.Option$8.process(Option.java:248)
[ERROR] ... 16 more
[ERROR] CodesnippetDoclet: error - fatal exception
[ERROR] javadoc: error - an unknown error has occurredAny guidance would be hugely appreciated. Thanks!
Support package-list and element-list to enable links to packages
JDK 10 onwards, the file containing the list of packages that is used for linking in Javadoc was renamed from package-list to element-list.
See https://bugs.java.com/bugdatabase/view_bug.do?bug_id=8191363
codesnippet4javadoc should support reading list of packages from either of these files. Without this, maven javadoc plugin logs a warning for JDK 10 and above:
[WARNING] javadoc: warning - Error reading file: /path/to/package/target/javadoc-bundle-options/package-list
JavaDoc fails if doclint is set to 'all' under JDK 17
If my build has 'doclint' set to 'all' (in Maven in my case), I get the following error output:
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-javadoc-plugin:3.3.0:jar (attach-javadocs) on project test: MavenReportException: Error while generating Javadoc:
[ERROR] Exit code: 4 - error: fatal error encountered: java.lang.IncompatibleClassChangeError: Expected static method 'boolean com.sun.tools.doclint.DocLint.isValidOption(java.lang.String)'
[ERROR] error: Please file a bug against the javadoc tool via the Java bug reporting page
[ERROR] (http://bugreport.java.com) after checking the Bug Database (http://bugs.java.com)
[ERROR] for duplicates. Include error messages and the following diagnostic in your report. Thank you.
[ERROR] java.lang.IncompatibleClassChangeError: Expected static method 'boolean com.sun.tools.doclint.DocLint.isValidOption(java.lang.String)'
[ERROR] at com.sun.tools.oldlets.formats.html.ConfigurationImpl.validOptions(ConfigurationImpl.java:512)
[ERROR] at com.sun.tools.oldlets.formats.html.HtmlDoclet.validOptions(HtmlDoclet.java:316)
[ERROR] at org.apidesign.javadoc.codesnippet.Doclet.validOptions(Doclet.java:297)
[ERROR] at org.apidesign.javadoc.codesnippet.Doclet$DelegatingOption.process(Doclet.java:221)
[ERROR] at jdk.javadoc/jdk.javadoc.internal.tool.Start.consumeDocletOption(Start.java:630)
[ERROR] at jdk.javadoc/jdk.javadoc.internal.tool.Start.parseArgs(Start.java:824)
[ERROR] at jdk.javadoc/jdk.javadoc.internal.tool.Start.parseAndExecute(Start.java:498)
[ERROR] at jdk.javadoc/jdk.javadoc.internal.tool.Start.begin(Start.java:393)
[ERROR] at jdk.javadoc/jdk.javadoc.internal.tool.Start.begin(Start.java:342)
[ERROR] at jdk.javadoc/jdk.javadoc.internal.tool.Main.execute(Main.java:63)
[ERROR] at jdk.javadoc/jdk.javadoc.internal.tool.Main.main(Main.java:52)
[ERROR] 2 errors
Removing the <doclint>all</doclint> line gets me past this issue.
Add support for JEP 413 - code snippets in Java API Documentation
It would be great to be able to transition away from the codesnippets4javadoc library over time as the JEP 413 support finds its way into JDK 18 (hopefully). If the codesnippets4javadoc library could support the existing and new javadoc syntax, we could then transition our snippets to the new syntax and only include the codesnippets4javadoc library conditionally on builds where the JDK version is less than 18.
Adding this as a feature request, but I may look into implementing this at some point in the future.
Version 0.31 doesn't work on JDK13 and prints warnings when using JDK 9-12
When using codesnippet tool with jdk 9+, I see the warnings below. I followed the instructions provided here and the doclet itself worked but would be great to not have these warnings.
javadoc: warning - The old Doclet and Taglet APIs in the packages
[WARNING] com.sun.javadoc, com.sun.tools.doclets and their implementations
[WARNING] are planned to be removed in a future JDK release. These
[WARNING] components have been superseded by the new APIs in jdk.javadoc.doclet.
[WARNING] Users are strongly recommended to migrate to the new APIs.
Don't use default system encoding for source files parsing
I work on a project with UTF-8 source code and a few code snippets parsed with this Doclet. Some of these snippets include UTF-8 special characters, but on systems with another encoding as default (ie ISO-8859-1), they are parsed as the default system encoding instead of the one configured for Javadoc.
The issue seems to come from the Snippets.scanDir method, where there is a call to Charset.defaultCharset().
The charset used here should be the same as the "encoding" parameter passed to the javadoc command, or at least be configurable at the Doclet level.
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.