Fix Javadoc issues per Oracle conventions

src/main/java/org/apache/commons/xml/secure/FallbackIgnoreEntityResolver2.java

@@ -55,9 +55,9 @@ final class FallbackIgnoreEntityResolver2 extends DefaultHandler2 {
     /**
      * Resolves {@code systemId} against {@code baseURI}.
      *
-     * @param baseURI  The absolute base URI to resolve against, or {@code null} if none is available.
-     * @param systemId The system identifier, possibly relative to {@code baseURI}.
-     * @return The absolutized system identifier, or {@code systemId} unchanged when it cannot or need not be resolved.
+     * @param baseURI  the absolute base URI to resolve against, or {@code null} if none is available
+     * @param systemId the system identifier, possibly relative to {@code baseURI}
+     * @return the absolutized system identifier, or {@code systemId} unchanged when it cannot or need not be resolved
      */
     private static String absolutize(final String baseURI, final String systemId) {
         if (systemId == null || baseURI == null) {
@@ -79,7 +79,7 @@ private static String absolutize(final String baseURI, final String systemId) {
     /**
      * Constructs a new ignore-all floor with an optional caller-supplied resolver.
      *
-     * @param delegate The caller-supplied resolver, or {@code null} for a pure ignore-all floor.
+     * @param delegate the caller-supplied resolver, or {@code null} for a pure ignore-all floor
      */
     FallbackIgnoreEntityResolver2(final EntityResolver delegate) {
         this.delegate = delegate;
@@ -88,7 +88,7 @@ private static String absolutize(final String baseURI, final String systemId) {
     /**
      * Gets the delegate provided by the constructor or set by {@link #setDelegate}, may be {@code null}.
      *
-     * @return The delegate provided by the constructor or set by {@link #setDelegate}, may be {@code null}.
+     * @return the delegate provided by the constructor or set by {@link #setDelegate}, may be {@code null}
      */
     EntityResolver getDelegate() {
         return delegate;
@@ -105,13 +105,13 @@ public InputSource getExternalSubset(final String name, final String baseURI) th
      * fetched nor leaked and the parse continues with no replacement text. The returned source echoes the requested identifiers (with {@code systemId}
      * absolutized): the parser reads the empty byte stream, but Xerces still derives the entity's base URI from the system id and fails on a {@code null} one.
      *
-     * @param name     The entity name, or {@code null} on the 2-arg resolution path.
-     * @param publicId The public identifier, or {@code null} if none.
-     * @param baseURI  The base URI for relative resolution, or {@code null}.
-     * @param systemId The system identifier of the unresolved entity.
-     * @return an empty {@link InputSource} carrying the requested identifiers.
-     * @throws SAXException when {@value SecureException#THROW_ON_UNRESOLVED} is set: unresolved references are rejected instead of resolved to empty.
-     * @throws IOException  never by the default implementation.
+     * @param name     the entity name, or {@code null} on the 2-arg resolution path
+     * @param publicId the public identifier, or {@code null} if none
+     * @param baseURI  the base URI for relative resolution, or {@code null}
+     * @param systemId the system identifier of the unresolved entity
+     * @return an empty {@link InputSource} carrying the requested identifiers
+     * @throws IOException  never by the default implementation
+     * @throws SAXException when {@value SecureException#THROW_ON_UNRESOLVED} is set: unresolved references are rejected instead of resolved to empty
      */
     private InputSource onUnresolved(final String name, final String publicId, final String baseURI, final String systemId) throws SAXException {
         if (SecureException.throwOnUnresolved()) {
@@ -148,7 +148,7 @@ private InputSource resolveWithDelegate(final String name, final String publicId
     /**
      * Replaces the caller resolver consulted ahead of the floor; lets a single floor instance back successive {@code setEntityResolver} calls.
      *
-     * @param delegate The caller-supplied resolver, or {@code null} for a pure ignore-all floor.
+     * @param delegate the caller-supplied resolver, or {@code null} for a pure ignore-all floor
      */
     void setDelegate(final EntityResolver delegate) {
         this.delegate = delegate;

src/main/java/org/apache/commons/xml/secure/FallbackIgnoreLSResourceResolver.java

@@ -52,7 +52,7 @@ final class FallbackIgnoreLSResourceResolver implements LSResourceResolver {
     /**
      * Constructs a new resolver that consults the given delegate and ignores whatever it does not resolve.
      *
-     * @param delegate optional caller-supplied resolver to consult first; may be {@code null}.
+     * @param delegate optional caller-supplied resolver to consult first; may be {@code null}
      */
     FallbackIgnoreLSResourceResolver(final LSResourceResolver delegate) {
         this.delegate = delegate;
@@ -61,7 +61,7 @@ final class FallbackIgnoreLSResourceResolver implements LSResourceResolver {
     /**
      * Gets the delegate provided by the constructor or set by {@link #setDelegate}, may be {@code null}.
      *
-     * @return The delegate provided by the constructor or set by {@link #setDelegate}, may be {@code null}.
+     * @return the delegate provided by the constructor or set by {@link #setDelegate}, may be {@code null}
      */
     LSResourceResolver getDelegate() {
         return delegate;
@@ -91,7 +91,7 @@ public LSInput resolveResource(final String type, final String namespaceURI, fin
     /**
      * Sets the delegate to consult first, replacing any previous delegate. A {@code null} value removes the delegate and leaves a pure ignore-all floor.
      *
-     * @param delegate The delegate to consult first, or {@code null} for a pure ignore-all floor.
+     * @param delegate the delegate to consult first, or {@code null} for a pure ignore-all floor
      */
     void setDelegate(final LSResourceResolver delegate) {
         this.delegate = delegate;

src/main/java/org/apache/commons/xml/secure/FallbackIgnoreURIResolver.java

@@ -61,9 +61,9 @@ final class FallbackIgnoreURIResolver implements URIResolver {
      * received cannot surface in another resolution.
      * </p>
      *
-     * @param factory the factory to create the document builder with.
-     * @return a new empty document.
-     * @throws IllegalStateException Thrown if the factory cannot supply a {@link javax.xml.parsers.DocumentBuilder} satisfying its configuration.
+     * @param factory the factory to create the document builder with
+     * @return a new empty document
+     * @throws IllegalStateException thrown if the factory cannot supply a {@link javax.xml.parsers.DocumentBuilder} satisfying its configuration
      */
     private static Document newEmptyDocument(final DocumentBuilderFactory factory) {
         try {
@@ -89,9 +89,9 @@ private static Document newEmptyDocument(final DocumentBuilderFactory factory) {
     /**
      * Constructs a new resolver.
      *
-     * @param delegate         the resolver to delegate resolution to; may be {@code null}.
-     * @param emptySource      the empty-{@link Source} supplier for the ignore outcome, or {@code null} for the default empty DOM document.
-     * @param overrideDefaultParser whether the opted-in rewrite should use the pluggable parser lookup instead of the platform's built-in parser, read at each resolution.
+     * @param delegate         the resolver to delegate resolution to; may be {@code null}
+     * @param emptySource      the empty-{@link Source} supplier for the ignore outcome, or {@code null} for the default empty DOM document
+     * @param overrideDefaultParser whether the opted-in rewrite should use the pluggable parser lookup instead of the platform's built-in parser, read at each resolution
      */
     FallbackIgnoreURIResolver(final URIResolver delegate, final Supplier<Source> emptySource, final BooleanSupplier overrideDefaultParser) {
         this.delegate = delegate;
@@ -103,7 +103,7 @@ private static Document newEmptyDocument(final DocumentBuilderFactory factory) {
     /**
      * Gets the delegate provided by the constructor or set by {@link #setDelegate}, may be {@code null}.
      *
-     * @return The delegate provided by the constructor or set by {@link #setDelegate}, may be {@code null}.
+     * @return the delegate provided by the constructor or set by {@link #setDelegate}, may be {@code null}
      */
     URIResolver getDelegate() {
         return delegate;
@@ -112,8 +112,8 @@ URIResolver getDelegate() {
     /**
      * {@inheritDoc}
      *
-     * @throws FactoryConfigurationError Thrown from a factory in case of a {@link java.util.ServiceConfigurationError service
-     *                                   configuration error} or if the implementation is not available or cannot be instantiated.
+     * @throws FactoryConfigurationError thrown from a factory in case of a {@link java.util.ServiceConfigurationError service
+     *                                   configuration error} or if the implementation is not available or cannot be instantiated
      */
     @Override
     public Source resolve(final String href, final String base) throws TransformerException {
@@ -131,7 +131,7 @@ public Source resolve(final String href, final String base) throws TransformerEx
     /**
      * Sets the delegate to consult first, replacing any previous delegate. A {@code null} value removes the delegate and leaves a pure ignore-all floor.
      *
-     * @param delegate The delegate to consult first, or {@code null} for a pure ignore-all floor.
+     * @param delegate the delegate to consult first, or {@code null} for a pure ignore-all floor
      */
     void setDelegate(final URIResolver delegate) {
         this.delegate = delegate;

src/main/java/org/apache/commons/xml/secure/FallbackIgnoreXMLResolver.java

@@ -45,7 +45,7 @@ final class FallbackIgnoreXMLResolver implements XMLResolver {
     /**
      * Constructs a new resolver that consults the given delegate and ignores whatever it does not resolve.
      *
-     * @param delegate optional caller-supplied resolver to consult first; may be {@code null}.
+     * @param delegate optional caller-supplied resolver to consult first; may be {@code null}
      */
     FallbackIgnoreXMLResolver(final XMLResolver delegate) {
         this.delegate = delegate;
@@ -54,7 +54,7 @@ final class FallbackIgnoreXMLResolver implements XMLResolver {
     /**
      * Gets the delegate provided by the constructor or set by {@link #setDelegate}, may be {@code null}.
      *
-     * @return The delegate provided by the constructor or set by {@link #setDelegate}, may be {@code null}.
+     * @return the delegate provided by the constructor or set by {@link #setDelegate}, may be {@code null}
      */
     XMLResolver getDelegate() {
         return delegate;
@@ -78,7 +78,7 @@ public Object resolveEntity(final String publicID, final String systemID, final
      * A null value removes the delegate and leaves a pure ignore-all floor.
      * </p>
      *
-     * @param delegate The delegate to consult first, replacing any previous delegate.
+     * @param delegate the delegate to consult first, replacing any previous delegate
      */
     void setDelegate(final XMLResolver delegate) {
         this.delegate = delegate;

src/main/java/org/apache/commons/xml/secure/MethodHandleFactory.java

@@ -35,11 +35,11 @@ interface ThrowableCallable<V> {
     /**
      * Finds a static method handle for the given class, method name, where the class is also the return type.
      *
-     * @param refcAndReturnType The class to search for the method and the return type.
-     * @param name              The name of the method.
-     * @return The method handle, or {@code null} if not found.
-     * @throws SecurityException    Thrown if a security manager is present and it <a href="MethodHandles.Lookup.html#secmgr">refuses access</a>.
-     * @throws NullPointerException Thrown if any argument is null.
+     * @param refcAndReturnType the class to search for the method and the return type
+     * @param name              the name of the method
+     * @return the method handle, or {@code null} if not found
+     * @throws NullPointerException thrown if any argument is null
+     * @throws SecurityException    thrown if a security manager is present and it <a href="MethodHandles.Lookup.html#secmgr">refuses access</a>
      */
     static MethodHandle findStatic(final Class<?> refcAndReturnType, final String name) {
         try {
@@ -56,13 +56,13 @@ static MethodHandle findStatic(final Class<?> refcAndReturnType, final String na
      * running platform does not have it.
      * </p>
      *
-     * @param refc           The class to search for the method.
-     * @param name           The name of the method.
-     * @param returnType     The method's return type.
-     * @param parameterTypes The method's parameter types.
-     * @return The method handle, or {@code null} if not found.
-     * @throws SecurityException    Thrown if a security manager is present and it <a href="MethodHandles.Lookup.html#secmgr">refuses access</a>.
-     * @throws NullPointerException Thrown if any argument is null.
+     * @param refc           the class to search for the method
+     * @param name           the name of the method
+     * @param returnType     the method's return type
+     * @param parameterTypes the method's parameter types
+     * @return the method handle, or {@code null} if not found
+     * @throws NullPointerException thrown if any argument is null
+     * @throws SecurityException    thrown if a security manager is present and it <a href="MethodHandles.Lookup.html#secmgr">refuses access</a>
      */
     static MethodHandle findVirtual(final Class<?> refc, final String name, final Class<?> returnType, final Class<?>... parameterTypes) {
         try {

src/main/java/org/apache/commons/xml/secure/SaxonProvider.java

@@ -91,7 +91,9 @@ private static final class SecureConfiguration extends Configuration {
 
         private static final String JDK_DEFAULT_PARSER = "#DEFAULT";
 
-        /** Collection-level ignore: {@code fn:collection()} and {@code fn:uri-collection()} resolve to an empty collection instead of fetching. */
+        /**
+         * Collection-level ignore: {@code fn:collection()} and {@code fn:uri-collection()} resolve to an empty collection instead of fetching.
+         */
         private static final CollectionFinder EMPTY_COLLECTION_FINDER = (context, collectionURI) -> {
             if (SecureException.throwOnUnresolved()) {
                 throw new XPathException(SecureException.forbidden("collection", null, null, collectionURI, null));
@@ -144,7 +146,7 @@ static XPathFactory configure(final XPathFactory factory) {
     /**
      * The empty-{@link Source} shape Saxon's consumers expect, for the {@link FallbackIgnoreURIResolver} floor the TrAX wrapper installs.
      *
-     * @return a supplier for Saxon's empty {@link Source}.
+     * @return a supplier for Saxon's empty {@link Source}
      */
     static Supplier<Source> emptySourceSupplier() {
         return SaxonProviderConfigurer.emptySourceSupplier();
@@ -154,8 +156,8 @@ static Supplier<Source> emptySourceSupplier() {
      * Tests whether the factory class is Saxon's, by package prefix, so public subclasses such as {@code net.sf.saxon.BasicTransformerFactory} route to the
      * same locked-down {@link Configuration} as the factory registered for JAXP lookup.
      *
-     * @param factoryClass The factory implementation class.
-     * @return Whether the class lives in Saxon's open-source or commercial packages.
+     * @param factoryClass the factory implementation class
+     * @return whether the class lives in Saxon's open-source or commercial packages
      */
     static boolean isSaxon(final Class<?> factoryClass) {
         final String name = factoryClass.getName();

src/main/java/org/apache/commons/xml/secure/SecureDocumentBuilder.java

@@ -46,8 +46,8 @@ final class SecureDocumentBuilder extends DocumentBuilder {
     /**
      * Constructs a new instance.
      *
-     * @param delegate the delegate to wrap; must not be {@code null}.
-     * @throws NullPointerException if {@code delegate} is {@code null}.
+     * @param delegate the delegate to wrap; must not be {@code null}
+     * @throws NullPointerException if {@code delegate} is {@code null}
      */
     SecureDocumentBuilder(final DocumentBuilder delegate) {
         this.delegate = Objects.requireNonNull(delegate, "delegate");