Skip to content

Commit 1e10600

Browse files
manticore-projectsmanticore-projects
committed
fix: option handling
Signed-off-by: manticore-projects <andreas@manticore-projects.com>
1 parent a95481b commit 1e10600

File tree

6 files changed

+84
-54
lines changed

6 files changed

+84
-54
lines changed

‎README.md‎

Lines changed: 25 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,14 @@
22

33
[Website](https://www.manticore-projects.com/XMLDoclet) | [Documentation](https://www.manticore-projects.com/XMLDoclet/usage.html) | [Example](https://www.manticore-projects.com/JSQLParser/javadoc_snapshot.html#analyticexpression)
44

5-
This library provides a doclet to output the javadoc comments from Java source code to a XML or a Restructured Text (*.rst) document.
5+
This library provides a doclet to output the javadoc comments from Java source code to a XML which can be transformed into:
66

7-
All modern JDKs 17, 21 and 23 are supported by XmlDoclet-2.+ and JDK 11 is supported by XMLDoc-1.4.+ only.
7+
- ReStructured Text for Python Sphinx and DocUtils
8+
- Markdown
9+
- DocBook XML for DBLatex PDF files
10+
- ASCII Doctor
811

9-
Planned support for Markdown (*.md), Docbook XML and ASCII Doctor (*.adoc). Sponsors or Contributors are most welcome.
12+
All modern JDKs 17, 21 and 23 are supported by XmlDoclet-2.+ and JDK 11 is supported by XMLDoc-1.4.+ only.
1013

1114
Example
1215
-------
@@ -17,42 +20,36 @@ Gradle
1720
------
1821

1922
```gradle
20-
repositories {
21-
// Sonatype OSSRH
22-
maven {
23-
url = uri('https://s01.oss.sonatype.org/content/repositories/snapshots/')
24-
}
25-
}
2623
configurations {
2724
xmlDoclet
2825
}
2926
dependencies {
3027
xmlDoclet 'com.manticore-projects.tools:xml-doclet:+'
3128
}
3229
tasks.register('xmldoc', Javadoc) {
33-
// optionally include some extra sources, e.g. generated source files
34-
// include = '..'
35-
30+
dependsOn(jar)
3631
source = sourceSets.main.allJava
37-
38-
// beware, that this folder will be overwritten hard by Gradle
32+
classpath = sourceSets.main.runtimeClasspath
33+
// beware: Gradle deletes this folder automatically and there is no switch-off
3934
destinationDir = reporting.file("xmlDoclet")
40-
options.docletpath = configurations.xmlDoclet.files.asType(List)
41-
42-
// for XmlDoclet-2.+ and JDK17+
43-
options.doclet = "com.manticore.tools.xmldoclet.XmlDoclet"
44-
45-
// for XmlDoclet-1.+ and JDK11+
46-
// options.doclet = "com.github.markusbernhardt.xmldoclet.XmlDoclet"
47-
48-
// transform to Restructured Text and copy to Sphinx Source folder
49-
options.addBooleanOption("rst", true)
50-
options.addStringOption("basePackage", "net.sf.jsqlparser")
35+
title = "API $version"
36+
37+
options {
38+
docletpath = configurations.xmlDoclet.files.asType(List)
39+
doclet = "com.manticore.tools.xmldoclet.XmlDoclet"
40+
addStringOption("basePackage", "com.manticore.tools.xmldoclet")
41+
42+
addBooleanOption("rst", true)
43+
addBooleanOption("adoc", true)
44+
addBooleanOption("md", true)
45+
addBooleanOption("docbook", true)
46+
addBooleanOption("withFloatingToc", true)
47+
}
5148
5249
doLast {
5350
copy {
5451
from reporting.file("xmlDoclet/javadoc.rst")
55-
into "${projectDir}/src/site/sphinx/"
52+
into "${projectDir}/src/site/sphinx"
5653
}
5754
}
5855
}
@@ -64,22 +61,13 @@ Maven
6461
If you are using maven you can use this library by adding the following report to your pom.xml:
6562

6663
```xml
67-
<repositories>
68-
<repository>
69-
<id>jsqlparser-snapshots</id>
70-
<snapshots>
71-
<enabled>true</enabled>
72-
</snapshots>
73-
<url>https://oss.sonatype.org/content/groups/public/</url>
74-
</repository>
75-
</repositories>
7664
<plugin>
7765
<groupId>org.apache.maven.plugins</groupId>
7866
<artifactId>maven-javadoc-plugin</artifactId>
7967
<executions>
8068
<execution>
8169
<id>xml-doclet</id>
82-
<phase>prepare-package</phase>
70+
<phase>prepare-package</phase>
8371
<goals>
8472
<goal>javadoc</goal>
8573
</goals>
@@ -90,7 +78,7 @@ If you are using maven you can use this library by adding the following report t
9078
<docletArtifact>
9179
<groupId>com.manticore-projects.tools</groupId>
9280
<artifactId>xml-doclet</artifactId>
93-
<version>2.0.0</version>
81+
<version>[2.1,)</version>
9482
</docletArtifact>
9583
</configuration>
9684
</execution>

‎build.gradle‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -294,12 +294,13 @@ tasks.register('xmldoc', Javadoc) {
294294
options {
295295
docletpath = configurations.xmlDoclet.files.asType(List)
296296
doclet = "com.manticore.tools.xmldoclet.XmlDoclet"
297+
addStringOption("basePackage", "com.manticore.tools.xmldoclet")
298+
297299
addBooleanOption("rst", true)
298300
addBooleanOption("adoc", true)
299301
addBooleanOption("md", true)
300302
addBooleanOption("docbook", true)
301303
addBooleanOption("withFloatingToc", true)
302-
addStringOption("basePackage", "com.manticore.tools.xmldoclet")
303304
}
304305

305306
doLast {
@@ -343,7 +344,7 @@ spotbugs {
343344

344345
pmd {
345346
consoleOutput = false
346-
//toolVersion = "6.46.0"
347+
toolVersion = "7.15.0"
347348

348349
sourceSets = [sourceSets.main]
349350

‎config/pmd/ruleset.xml‎

Lines changed: 1 addition & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -84,9 +84,7 @@ under the License.
8484
<property name="cycloOptions" value="" />
8585
</properties>
8686
</rule>
87-
<rule ref="category/java/design.xml/ExcessiveMethodLength" />
88-
<rule ref="category/java/bestpractices.xml/SwitchStmtsShouldHaveDefault" />
89-
87+
<rule ref="category/java/bestpractices.xml/NonExhaustiveSwitch" />
9088
<rule ref="category/java/errorprone.xml/AvoidBranchingStatementAsLastInLoop" />
9189
<rule ref="category/java/errorprone.xml/AvoidDecimalLiteralsInBigDecimalConstructor" />
9290
<rule ref="category/java/errorprone.xml/AvoidMultipleUnaryOperators" />
@@ -96,15 +94,6 @@ under the License.
9694
<rule ref="category/java/errorprone.xml/ClassCastExceptionWithToArray" />
9795
<rule ref="category/java/errorprone.xml/DontUseFloatTypeForLoopIndices" />
9896
<rule ref="category/java/errorprone.xml/EmptyCatchBlock" />
99-
<rule ref="category/java/errorprone.xml/EmptyFinallyBlock" />
100-
<rule ref="category/java/errorprone.xml/EmptyIfStmt" />
101-
<rule ref="category/java/errorprone.xml/EmptyInitializer" />
102-
<rule ref="category/java/errorprone.xml/EmptyStatementBlock" />
103-
<rule ref="category/java/errorprone.xml/EmptyStatementNotInLoop" />
104-
<rule ref="category/java/errorprone.xml/EmptySwitchStatements" />
105-
<rule ref="category/java/errorprone.xml/EmptySynchronizedBlock" />
106-
<rule ref="category/java/errorprone.xml/EmptyTryBlock" />
107-
<rule ref="category/java/errorprone.xml/EmptyWhileStmt" />
10897
<rule ref="category/java/errorprone.xml/JumbledIncrementer" />
10998
<rule ref="category/java/errorprone.xml/MisplacedNullCheck" />
11099
<rule ref="category/java/errorprone.xml/OverrideBothEqualsAndHashcode" />

‎src/main/java/com/manticore/tools/xmldoclet/XmlDoclet.java‎

Lines changed: 25 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -136,6 +136,7 @@ public static void transform(
136136
if (parameter.getKey() != null && !parameter.getKey().isEmpty()) {
137137
final var name = new QName(parameter.getKey());
138138
if (parameter.getValue() != null) {
139+
LOGGER.log(Level.FINE, "Parameter " + name + " = " + parameter.getValue());
139140
final var values = new XdmAtomicValue(parameter.getValue());
140141
transformer.setParameter(name, values);
141142
} else {
@@ -186,10 +187,32 @@ public void save(final Root root) {
186187

187188
reporter.print(Diagnostic.Kind.NOTE, "Wrote XML to: " + xmlFile.getAbsolutePath());
188189

190+
// translate the Doclet CLI Options into XSL compatible parameters
191+
// filter out incompatible options like `-XLint:...`
189192
final var parameters = new HashMap<String, String>();
190193
for (final var option : options.get()) {
191-
final String optionValue = options.getOptionValue(option, "true");
192-
parameters.put(option.getParameters(), optionValue);
194+
// the name starts with a hyphen
195+
String name = option.getName();
196+
if (name.startsWith("-")) {
197+
name = name.substring(1);
198+
}
199+
200+
// loop through all possible options and check if it has been set
201+
if (options.hasOption(name)) {
202+
// if option is provided without an argument, assume it is a boolean switch
203+
// relevant for `withFloatingToc` especially
204+
String optionValue = options.getOptionValue(option, "true");
205+
if (optionValue == null || optionValue.isEmpty()) {
206+
optionValue = "true";
207+
}
208+
209+
if (name.contains(",") || name.contains(":")) {
210+
LOGGER.fine("Ignore " + name + " " + optionValue);
211+
} else {
212+
LOGGER.fine(name + " " + optionValue);
213+
parameters.put(name, optionValue);
214+
}
215+
}
193216
}
194217

195218
if (options.hasOption("rst")) {

‎src/site/sphinx/changelog.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,23 @@
22

33
Changelog of xml-doclet.
44

5+
## 2.1.0 (2025-07-13)
6+
7+
### Features
8+
9+
- support MD, ADOC, Docbook ([44ec5](https://github.com/manticore-projects/xml-doclet/commit/44ec50f40d4706d) manticore-projects)
10+
- working markdown stylesheet ([f4571](https://github.com/manticore-projects/xml-doclet/commit/f45710453e09854) manticore-projects)
11+
- working docbook stylesheet ([d61c5](https://github.com/manticore-projects/xml-doclet/commit/d61c5020563ebfe) manticore-projects)
12+
13+
### Other changes
14+
15+
16+
## 2.0.9 (2025-07-12)
17+
18+
### Features
19+
20+
- implement `Xdoclint` and `html5` options since those are set by Gradle and can't get switched off ([32ae4](https://github.com/manticore-projects/xml-doclet/commit/32ae49181922fc1) manticore-projects)
21+
522
## 2.0.8 (2025-07-12)
623

724
### Other changes

‎src/site/sphinx/javadoc.rst‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,18 @@
11

2+
.. raw:: html
3+
4+
<div id="floating-toc">
5+
<div class="search-container">
6+
<input type="button" id="toc-hide-show-btn"></input>
7+
<input type="text" id="toc-search" placeholder="Search" />
8+
</div>
9+
<ul id="toc-list"></ul>
10+
</div>
11+
12+
13+
214
#######################################################################
3-
API 2.1.0-SNAPSHOT
15+
API 2.2-SNAPSHOT
416
#######################################################################
517

618
Base Package: com.manticore.tools.xmldoclet

0 commit comments

Comments
 (0)