Skip to content

[XERCESJ-1781] fine tuning Javadoc linting #65

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
SingingBush wants to merge 2 commits into from
Closed

[XERCESJ-1781] fine tuning Javadoc linting #65

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cc080d6
[XERCESJ-1781] fine tuning Javadoc linting
SingingBush Nov 24, 2025
a58ab26
[XERCESJ-1781] fine tuning Javadoc linting
SingingBush Nov 25, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 50 additions & 30 deletions build.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ Authors:

==================================================================== -->
<project default="usage" basedir=".">

<!-- Xerces Java directories -->
<property name="build.dir" value="./build"/>
<property name="data.dir" value="./data"/>
Expand Down Expand Up @@ -179,10 +179,10 @@ Authors:

<copy file="${src.dir}/org/apache/xerces/jaxp/javax.xml.parsers.SAXParserFactory"
tofile="${build.dest}/META-INF/services/javax.xml.parsers.SAXParserFactory"/>

<copy file="${src.dir}/org/apache/xerces/jaxp/datatype/javax.xml.datatype.DatatypeFactory"
tofile="${build.dest}/META-INF/services/javax.xml.datatype.DatatypeFactory"/>

<copy file="${src.dir}/org/apache/xerces/jaxp/validation/javax.xml.validation.SchemaFactory"
tofile="${build.dest}/META-INF/services/javax.xml.validation.SchemaFactory"/>

Expand All @@ -198,11 +198,11 @@ Authors:
<!-- Prepares the source code -->
<!-- =================================================================== -->
<target name="prepare-src" depends="prepare-common">
<!-- Do not include this file in xercesImpl.jar. It prevents applications further down the
classpath from overriding the parser's default and may also cause an incompatible mix
of classes to be loaded leading to a failure such as a NoSuchMethodError. -->
<!-- <copy file="${src.dir}/org/apache/xerces/parsers/org.apache.xerces.xni.parser.XMLParserConfiguration"
<!-- Do not include this file in xercesImpl.jar. It prevents applications further down the
classpath from overriding the parser's default and may also cause an incompatible mix
of classes to be loaded leading to a failure such as a NoSuchMethodError. -->
<!-- <copy file="${src.dir}/org/apache/xerces/parsers/org.apache.xerces.xni.parser.XMLParserConfiguration"
tofile="${build.dest}/META-INF/services/org.apache.xerces.xni.parser.XMLParserConfiguration"/> -->

<copy file="${src.dir}/org/apache/xerces/dom/org.w3c.dom.DOMImplementationSourceList"
Expand All @@ -220,7 +220,7 @@ Authors:
javax.xml.parsers.ConvertToURI.java">
</fileset>
</copy>

<!-- create English message bundles from the default ones -->
<copy file="${src.dir}/org/apache/xerces/impl/msg/DatatypeMessages.properties"
tofile="${build.src}/org/apache/xerces/impl/msg/DatatypeMessages_en.properties"/>
Expand Down Expand Up @@ -494,29 +494,29 @@ Authors:
<replace token="@xerces.internal" dir="${build.src}">
<replacevalue><![CDATA[<dl><dt><strong>INTERNAL:</strong></dt><dd>Usage of this class is not supported. It may be altered or removed at any time.</dd></dl>]]></replacevalue>
</replace>

<replace token="@xerces.experimental" dir="${build.src}">
<replacevalue><![CDATA[<dl><dt><strong>EXPERIMENTAL:</strong></dt><dd>This class should not be considered stable. It is likely to be altered or replaced in the future.</dd></dl>]]></replacevalue>
</replace>
</target>

<!-- =================================================================== -->
<!-- Creates the API documentation -->
<!-- =================================================================== -->
<target name="javadocs" depends="prepare-src">
<target name="javadocs" depends="prepare-src">

<condition property="additional.param" value=" -taglet org.apache.xerces.util.ExperimentalTaglet -taglet org.apache.xerces.util.InternalTaglet -tagletpath ${tools.dir}/bin/xerces2taglets.jar">
<available classname="com.sun.tools.doclets.Taglet"/>
</condition>

<antcall target="javadoc-replace" />

<condition property="additional.param" value="">
<not>
<available classname="com.sun.tools.doclets.Taglet"/>
</not>
</condition>

<mkdir dir='${build.dir}/docs/javadocs/api'/>
<javadoc packagenames='javax.xml.*,org.w3c.*,org.xml.*'
locale='en_US'
Expand All @@ -525,7 +525,11 @@ Authors:
windowtitle='XML Standard API' doctitle='XML Standard API'
bottom='${copyright}'
additionalparam='-quiet ${additional.param}'
/>
failonerror='no'
failonwarning='no'
>
<arg value="-Xdoclint:none"/>
</javadoc>
<mkdir dir='${build.dir}/docs/javadocs/xni'/>
<javadoc packagenames='org.apache.xerces.xni.*'
locale='en_US'
Expand All @@ -535,7 +539,11 @@ Authors:
doctitle='Xerces Native Interface'
bottom='${copyright}'
additionalparam='-quiet ${additional.param}'
/>
failonerror='yes'
failonwarning='yes'
Copy link
Contributor

@elharo elharo Nov 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No. I do not want the build to fail on a warning. I'm not sure it should fail on an error here, but definitely not on a warning

Copy link

@mlocati mlocati Nov 24, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why not? It helps having a cleaner codebase imho

Copy link
Contributor Author

@SingingBush SingingBush Nov 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've only set yes on the sections that don't have any errors or warnings. This branch passes, so setting yes here is to ensure future changes don't introduce problems.

Copy link
Contributor Author

@SingingBush SingingBush Nov 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Saying that, I just saw that behaviour is different on the CI build. I'll take a look at why it's passing locally but not on CI

Copy link
Contributor Author

@SingingBush SingingBush Nov 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've been using JDK 8 locally, I'll make sure to fix errors for newer JDK linter problems as well.

Copy link
Contributor Author

@SingingBush SingingBush Nov 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was simply that later JDKs also error if table in a package.html file don't have a caption. Fixed now

>
<arg value="-Xdoclint:html,accessibility"/>
</javadoc>
<mkdir dir='${build.dir}/docs/javadocs/xs'/>
<javadoc packagenames='org.apache.xerces.xs, org.apache.xerces.xs.datatypes'
locale='en_US'
Expand All @@ -545,7 +553,11 @@ Authors:
doctitle='XML Schema API'
bottom='${copyright}'
additionalparam='-quiet ${additional.param}'
/>
failonerror='yes'
failonwarning='yes'
Copy link
Contributor

@elharo elharo Nov 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

revert

>
<arg value="-Xdoclint:html,accessibility"/>
</javadoc>

<mkdir dir='${build.dir}/docs/javadocs/xerces2'/>
<javadoc packagenames='org.apache.xerces.dom.*,
Expand All @@ -564,7 +576,11 @@ Authors:
doctitle='Xerces2 Implementation'
bottom='${copyright}'
additionalparam='-quiet ${additional.param}'
/>
failonerror='no'
failonwarning='no'
>
<arg value="-Xdoclint:html"/>
</javadoc>
<mkdir dir='${build.dir}/docs/javadocs/other'/>
<javadoc packagenames='org.apache.html.*,
org.apache.wml.*,
Expand All @@ -575,7 +591,11 @@ Authors:
windowtitle='Other Classes' doctitle='Other Classes'
bottom='${copyright}'
additionalparam='-quiet ${additional.param}'
/>
failonerror='yes'
failonwarning='yes'
Copy link
Contributor

@elharo elharo Nov 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

revert

>
<arg value="-Xdoclint:html"/>
</javadoc>
</target>

<!-- =================================================================== -->
Expand Down Expand Up @@ -1075,7 +1095,7 @@ Authors:

<copy file="${src.dir}/org/apache/xerces/dom/org.apache.xerces.dom.DOMImplementationSourceImpl"
tofile="${build.dest}/META-INF/services/org.w3c.dom.DOMImplementationSourceList"/>

<!-- delete META-INF/services files for DatatypeFactory/SchemaFactory
since no implementation is provided in this jar -->
<delete file="${build.dest}/META-INF/services/javax.xml.datatype.DatatypeFactory"/>
Expand Down Expand Up @@ -1203,7 +1223,7 @@ Authors:
token="return ((XSComplexTypeDecl) type).isDOMDerivedFrom(" value="return false;"/>
<replace file="${build.dir}/src/org/apache/xerces/dom/ElementNSImpl.java"
token="typeNamespaceArg, typeNameArg, derivationMethod);" value=""/>

<!-- HACK: Remove references to schema DOM from DOMUtil -->
<replace file="${build.dir}/src/org/apache/xerces/util/DOMUtil.java"
token="import org.apache.xerces.impl.xs.opti.ElementImpl;" value=""/>
Expand All @@ -1221,7 +1241,7 @@ Authors:
token="((org.apache.xerces.impl.xs.opti.NodeImpl)node).setReadOnly(false, false);" value="return;"/>
<replace file="${build.dir}/src/org/apache/xerces/util/DOMUtil.java"
token="return ((org.apache.xerces.impl.xs.opti.NodeImpl)node).getReadOnly();" value="return false;"/>

<!-- HACK: Remove references to schema validation support from org.apache.xerces.jaxp -->
<replace file="${build.dir}/src/org/apache/xerces/jaxp/SAXParserImpl.java"
token="import org.apache.xerces.impl.xs.XMLSchemaValidator;" value=""/>
Expand All @@ -1247,7 +1267,7 @@ Authors:
token="(XSGrammarPoolContainer) grammar, fSchemaValidationManager);" value=""/>
<replace file="${build.dir}/src/org/apache/xerces/jaxp/SAXParserImpl.java"
token="fSAXParser.fUnparsedEntityHandler.reset();" value=""/>

<replace file="${build.dir}/src/org/apache/xerces/jaxp/DocumentBuilderImpl.java"
token="import org.apache.xerces.impl.xs.XMLSchemaValidator;" value=""/>
<replace file="${build.dir}/src/org/apache/xerces/jaxp/DocumentBuilderImpl.java"
Expand All @@ -1272,7 +1292,7 @@ Authors:
token="(XSGrammarPoolContainer) grammar, fSchemaValidationManager);" value=""/>
<replace file="${build.dir}/src/org/apache/xerces/jaxp/DocumentBuilderImpl.java"
token="fUnparsedEntityHandler.reset();" value=""/>

<replace file="${build.dir}/src/org/apache/xerces/jaxp/SAXParserFactoryImpl.java"
token="return grammar;" value="throw new UnsupportedOperationException();"/>
<replace file="${build.dir}/src/org/apache/xerces/jaxp/SAXParserFactoryImpl.java"
Expand Down Expand Up @@ -1552,7 +1572,7 @@ Authors:
</manifest>
<metainf dir="." includes="LICENSE,NOTICE"/>
</jar>
</target>
</target>

<!-- =================================================================== -->
<!-- Builds xercesImpl, xml-apis and sample jars with Schema 1.1 support -->
Expand All @@ -1572,10 +1592,10 @@ Authors:
<target name="xjavac-jar" depends="prepare">
<mkdir dir="${build.src}"/>
<mkdir dir="${build.dest}"/>

<copy file="${tools.dir}/src/XJavac.java"
tofile="${build.src}/org/apache/xerces/util/XJavac.java"/>

<javac srcdir="${build.src}"
destdir="${build.dest}"
source="${javac.source}"
Expand All @@ -1587,7 +1607,7 @@ Authors:
optimize="${optimize}"
includeAntRuntime="false"
includeJavaRuntime="false"/>

<jar jarfile="${build.dir}/${jar.xjavac}"
basedir="${build.dest}"
compress="true"
Expand Down
2 changes: 1 addition & 1 deletion src/org/apache/xerces/impl/xpath/regex/REUtil.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -218,7 +218,7 @@ else if (next == '^' && offset + 1 < len) {

/**
* Sample entry.
* <div>Usage: <KBD>org.apache.xerces.utils.regex.REUtil &lt;regex&gt; &lt;string&gt;</KBD></div>
* <p>Usage: <code>org.apache.xerces.utils.regex.REUtil &lt;regex&gt; &lt;string&gt;</code></p>
Copy link
Contributor

@elharo elharo Nov 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should probably be samp instead of code if I recall correctly

Copy link
Contributor Author

@SingingBush SingingBush Nov 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can't use samp in Javadoc due to:

error: unknown tag: samp

could use pre if preferred

*/
public static void main(String[] argv) {
String pattern = null;
Expand Down
20 changes: 10 additions & 10 deletions src/org/apache/xerces/impl/xs/models/XSCMValidator.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,8 +54,9 @@ public interface XSCMValidator {
/**
* The method corresponds to one transaction in the content model.
*
* @param elementName
* @param state Current state
* @param elementName the element's qualified name
* @param state current state of the content model
* @param subGroupHandler the substitution group handler
* @return element decl or wildcard decl that
* corresponds to the element from the Schema grammar
*/
Expand Down Expand Up @@ -94,14 +95,13 @@ public interface XSCMValidator {
* or <code>null</code> if no occurrence counting was being performed at the
* current state.</p>
*
* <p>If an array is returned it will have a length == 4 and will contain:
* <ul>
* <li>a[0] :: min occurs</li>
* <li>a[1] :: max occurs</li>
* <li>a[2] :: current value of the counter</li>
* <li>a[3] :: identifier for the repeating term</li>
* </ul>
* </p>
* <p>If an array is returned it will have a length == 4 and will contain:</p>
* <ul>
* <li>a[0] :: min occurs</li>
* <li>a[1] :: max occurs</li>
* <li>a[2] :: current value of the counter</li>
* <li>a[3] :: identifier for the repeating term</li>
* </ul>
*
* @param state the current state
* @return an array containing information about the current repeating term
Expand Down
3 changes: 2 additions & 1 deletion src/org/apache/xerces/xs/datatypes/XSDateTime.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,9 @@
* table shows the methods defined for various XML Schema 1.0 built-in types. 'X'
* marks whether a particular method is defined for a particular type. Accessing undefined
* methods may return unexpected values.
*
*
* <table border="1">
* <caption>Mappings between XML Schema 1.0 date-time related types and their supported accessors</caption>
* <tr>
* <td> XML Schema Datatype </td>
* <td> getYears() </td>
Expand Down
2 changes: 2 additions & 0 deletions src/org/apache/xerces/xs/datatypes/package.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@
<BR>
<BR>
<TABLE border="1">
<caption>Mappings between XML Schema Data Type and applicable interfaces</caption>
<TBODY>
<TR>
<TD style="width: 332px; text-align: center;">XML Schema Data Type</TD>
Expand Down Expand Up @@ -225,6 +226,7 @@
<P><BR>
</P>
<TABLE border="1">
<caption>Mappings between XML Schema Data Type and applicable method in XSDateTime*</caption>
<TBODY>
<TR>
<TD style="width: 308px; text-align: center;">XML Schema Data Type</TD>
Expand Down