Fix Javadoc issues in org.apache.xerces.util per Oracle conventions #40

elharo · 2025-10-25T16:42:40Z

These are automated fixes.

Copilot

Pull Request Overview

This PR standardizes Javadoc formatting in the org.apache.xerces.util package to comply with Oracle's Javadoc conventions. The changes focus on updating documentation style while preserving code functionality.

Key changes include:

Converting Javadoc parameter descriptions from uppercase to lowercase format (e.g., "The" → "the")
Standardizing sentence-ending punctuation in field and method documentation
Removing extraneous blank lines and asterisks in Javadoc comments

Reviewed Changes

Copilot reviewed 41 out of 44 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
XMLStringBuffer.java	Removed empty Javadoc blocks and standardized method documentation
XMLResourceIdentifierImpl.java	Updated parameter descriptions to lowercase and removed trailing blank lines
XMLLocatorWrapper.java	Removed trailing blank line from class-level Javadoc
XMLGrammarPoolImpl.java	Standardized parameter and return tag formatting
XMLErrorCode.java	Updated field comments with proper sentence endings and parameter descriptions
XMLEntityDescriptionImpl.java	Converted parameter descriptions to lowercase
XMLChar.java	Fixed period placement in author tag and updated parameter/method descriptions
XMLCatalogResolver.java	Reordered exception tags and standardized field comment endings
XMLAttributesImpl.java	Relocated `@see` tag and updated parameter descriptions throughout
XML11Char.java	Standardized field comments and method descriptions with proper punctuation
URI.java	Reformatted multiline comments and converted `@exception` to `@throws` tags
SynchronizedSymbolTable.java	Updated parameter descriptions to lowercase
SymbolTable.java	Moved `@see` tag and standardized parameter formatting
SymbolHash.java	Updated method documentation with proper sentence endings
StAXLocationWrapper.java	Removed trailing blank line from class Javadoc
SoftReferenceSymbolTable.java	Relocated `@see` tag and updated constructor parameters
ShadowedSymbolTable.java	Standardized parameter descriptions
SecurityManager.java	Updated field comment endings with periods
SAXMessageFormatter.java	Converted parameter descriptions and exception tags
SAXLocatorWrapper.java	Removed trailing blank line
SAXInputSource.java	Updated setter method parameter descriptions
PrimeNumberSequenceGenerator.java	Relocated `@xerces.internal` tag
ParserConfigurationSettings.java	Standardized parameter descriptions and exception tags
NamespaceSupport.java	Updated parameter description format
MessageFormatter.java	Relocated `@see` tag and updated method documentation
LocatorProxy.java	Removed trailing blank line
JAXPNamespaceContextWrapper.java	Removed trailing blank line
IntStack.java	Relocated author tag after blank line
HTTPInputSource.java	Updated field comments and constructor parameter descriptions
ErrorHandlerWrapper.java	Relocated `@see` tag and reformatted multiline comment
ErrorHandlerProxy.java	Removed trailing blank line
EntityResolverWrapper.java	Relocated `@see` tag and reordered exception tags
EntityResolver2Wrapper.java	Reordered exception tags
EncodingMap.java	Updated field comments and parameter descriptions
DefaultErrorHandler.java	Removed trailing blank line
DatatypeMessageFormatter.java	Standardized parameter and exception documentation
DOMUtil.java	Reformatted multiline comments with proper structure
DOMErrorHandlerWrapper.java	Relocated `@see` tag and updated field/parameter descriptions
DOMEntityResolverWrapper.java	Relocated `@see` tag and reordered exceptions
AugmentationsImpl.java	Reformatted method descriptions and parameter tags
AttributesProxy.java	Removed trailing blank line

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-10-25T16:50:02Z

src/org/apache/xerces/util/XMLChar.java

 * @author Michael Glavassevich, IBM
- * @author Rahul Srivastava, Sun Microsystems Inc.
- *
+ * @author Rahul Srivastava, Sun Microsystems Inc


The author tag is missing a period at the end. According to Oracle Javadoc conventions, author tags should end with appropriate punctuation (typically a period). This should be 'Sun Microsystems Inc.' to match the format used in other files.

Suggested change

* @author Rahul Srivastava, Sun Microsystems Inc

* @author Rahul Srivastava, Sun Microsystems Inc.

Copilot · 2025-10-25T16:50:02Z

src/org/apache/xerces/util/XMLGrammarPoolImpl.java

-     * @param desc The Grammar Description.
-     * @return     The removed grammar.
+     * @param desc the Grammar Description
+     * @return The removed grammar


Inconsistent capitalization in return tag. The return description starts with 'The' (uppercase) while other updated return tags in the same file use lowercase. This should be 'the removed grammar' to maintain consistency with the PR's standardization goal.

Suggested change

* @return The removed grammar

* @return the removed grammar

Copilot · 2025-10-25T16:50:03Z

src/org/apache/xerces/util/URI.java

-*
-**********************************************************************/
+/**
+ * *******************************************************************


The asterisk separator line creates unusual formatting. This should be a standard Javadoc comment without the asterisk line separator on line 25, as this non-standard formatting is inconsistent with Oracle Javadoc conventions.

Suggested change

* *******************************************************************

Copilot · 2025-10-25T16:50:03Z

src/org/apache/xerces/util/URI.java

-  *
-  ********************************************************************/
+  /**
+   * ****************************************************************


Similar to the previous comment, this asterisk separator line creates non-standard Javadoc formatting. The separator line with asterisks on line 62 should be removed to follow Oracle Javadoc conventions.

Copilot · 2025-10-25T16:50:03Z

src/org/apache/xerces/util/URI.java


-   /******************************************************************
+   /**
+    * ***************************************************************


The asterisk separator creates non-standard formatting. Line 75 should not contain asterisk separators as this violates Oracle Javadoc conventions.

Copilot · 2025-10-25T16:50:04Z

src/org/apache/xerces/util/ParserConfigurationSettings.java

+     *
+     * @param featureId the feature identifier
+     * @return true if the feature is supported
+     * @throws XMLConfigurationException thrown for configuration error.


Inconsistent sentence ending. The exception description ends with a period on line 187 ('error.'), but line 211 in the same file has the same text. One uses a period, creating inconsistency in the documentation style.

Copilot · 2025-10-25T16:50:04Z

src/org/apache/xerces/util/MessageFormatter.java

-     *
-     * @throws MissingResourceException Thrown if the message with the
-     *                                  specified key cannot be found.
+     * @return returns the formatted message


Redundant wording in return tag. The description 'returns the formatted message' on line 47 is redundant since @return already indicates that something is being returned. Should be '@return the formatted message' to match the style used elsewhere in the PR.

Suggested change

* @return returns the formatted message

* @return the formatted message

Copilot · 2025-10-25T16:50:04Z

src/org/apache/xerces/util/DOMErrorHandlerWrapper.java

- * @see DOMErrorHandler
- *
- * @author Gopal Sharma, SUN Microsystems Inc.
+ * @author Gopal Sharma, SUN Microsystems Inc


Missing period at end of author tag. Should be 'SUN MicroSystems Inc.' on line 37 to match Oracle Javadoc conventions and maintain consistency with other author tags that include periods.

Suggested change

* @author Gopal Sharma, SUN Microsystems Inc

* @author Gopal Sharma, SUN Microsystems Inc.

Copilot · 2025-10-25T16:50:05Z

src/org/apache/xerces/util/DOMEntityResolverWrapper.java

- *
- * @author Gopal Sharma, SUN MicroSystems Inc.
- * @author Elena Litani, IBM 
+ * @author Gopal Sharma, SUN MicroSystems Inc


Missing period at end of author tag. Should be 'SUN MicroSystems Inc.' on line 38 to follow Oracle Javadoc conventions and maintain consistency.

Suggested change

* @author Gopal Sharma, SUN MicroSystems Inc

* @author Gopal Sharma, SUN MicroSystems Inc.

Copilot · 2025-10-25T16:50:05Z

src/org/apache/xerces/util/AugmentationsImpl.java

-     * @param key    Identifier, can't be <code>null</code>
+     * Remove additional info from the Augmentations structure.
+     *
+     * @param key identifier, can't be <code>null</code>


Inconsistent capitalization in parameter description. On line 76, 'identifier' starts with lowercase, but on lines 47 and 65 in the same file, the same parameter uses lowercase. However, the pattern should be consistent. Since most have been changed to lowercase, this should remain lowercase, but verify consistency across all three occurrences.

SingingBush · 2025-10-26T15:03:09Z

just out of curiosity. was copilot used to generate these changes?

elharo · 2025-10-26T15:39:26Z

no, https://github.com/elharo/docfix

Fix Javadoc issues per Oracle conventions

a3256bc

elharo requested a review from Copilot October 25, 2025 16:47

elharo assigned mukulga and unassigned mukulga Oct 25, 2025

elharo requested a review from mukulga October 25, 2025 16:48

Copilot AI reviewed Oct 25, 2025

View reviewed changes

This was referenced Oct 25, 2025

Inc. and perhaps other abbreviations can end with a period where a non-abbreviation would not elharo/docfix#241

Closed

Failed to lowercase return tag elharo/docfix#242

Closed

Delete "returns" in a return tag elharo/docfix#243

Closed

Copilot AI mentioned this pull request Oct 30, 2025

Fix @return tag lowercasing when extra spaces present elharo/docfix#261

Merged

9 tasks

elharo closed this Oct 31, 2025

elharo deleted the util branch October 31, 2025 12:38

	* @author Rahul Srivastava, Sun Microsystems Inc
	* @author Rahul Srivastava, Sun Microsystems Inc.

	* @return returns the formatted message
	* @return the formatted message

	* @author Gopal Sharma, SUN Microsystems Inc
	* @author Gopal Sharma, SUN Microsystems Inc.

Fix Javadoc issues in org.apache.xerces.util per Oracle conventions #40

Fix Javadoc issues in org.apache.xerces.util per Oracle conventions #40

Uh oh!

Conversation

elharo commented Oct 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Oct 25, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 25, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 25, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 25, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 25, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 25, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 25, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 25, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 25, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 25, 2025

Choose a reason for hiding this comment

Uh oh!

SingingBush commented Oct 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

elharo commented Oct 26, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

elharo commented Oct 25, 2025 •

edited

Loading

SingingBush commented Oct 26, 2025 •

edited

Loading