MINOR: Fix PrimitiveStringifier class Javadoc to link UnsupportedOperationException#3651
Open
anxkhn wants to merge 1 commit into
Open
MINOR: Fix PrimitiveStringifier class Javadoc to link UnsupportedOperationException#3651anxkhn wants to merge 1 commit into
anxkhn wants to merge 1 commit into
Conversation
…ationException
The class-level Javadoc of PrimitiveStringifier stated that the overloaded
stringify(...) methods not implemented for the related types throw
{@link OperationNotSupportedException}. That link resolved to the checked
javax.naming.OperationNotSupportedException, which these unchecked methods
cannot throw, and it contradicted every method's own @throws tag. In fact all
overloads throw java.lang.UnsupportedOperationException.
Point the class Javadoc at UnsupportedOperationException and drop the now-unused
javax.naming import. Documentation-only, no behavioral change.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Rationale for this change
The class-level Javadoc of the public abstract class
PrimitiveStringifier(
parquet-column/src/main/java/org/apache/parquet/schema/PrimitiveStringifier.java)documents the wrong exception type. It states:
That
{@link}resolves tojavax.naming.OperationNotSupportedException, which isthe only reason the
import javax.naming.OperationNotSupportedException;exists inthe file. Two problems follow from this:
stringify(...)overload that is not implemented for a type actuallythrows
java.lang.UnsupportedOperationException, and each method's own@throwstag already documentsUnsupportedOperationException. So theclass-level contract contradicts every per-method contract in the same file.
javax.naming.OperationNotSupportedExceptionis a checked exception(
extends NamingException extends Exception). The uncheckedstringify(...)methods cannot declare or throw it, so the documented behavior is impossible
and would mislead a caller into catching the wrong exception type.
What changes are included in this PR?
A documentation-only change in one file:
{@link}atjava.lang.UnsupportedOperationException(no import needed), so the class contract matches the six per-method
@throwstags and the actual
throwstatements.import javax.naming.OperationNotSupportedException;,which existed solely to satisfy the incorrect link.
No behavioral change. Net diff is one import line removed and one word changed in
the Javadoc.
Are these changes tested?
This is a Javadoc/import-only change with no runtime behavior change, so no new
test is added. It was validated locally on
parquet-column(JDK 21, Maven 3.9):mvn -pl parquet-column -Dspotless.check.skip=true -DskipTests compilesucceeds,confirming the removed
javax.namingimport was unused.mvn -pl parquet-column javadoc:javadocsucceeds with no "reference not found"warning for
PrimitiveStringifier; the generated HTML now links the classdescription to
java.lang.UnsupportedOperationExceptionand contains nojavax.namingreference.mvn -pl parquet-column spotless:checksucceeds (0 files need reformatting).mvn -pl parquet-column -Dtest=TestPrimitiveStringifier testpasses(13 tests, 0 failures), confirming no behavioral change.
Are there any user-facing changes?
No. This only corrects Javadoc and removes a dead import. There is no API or
behavior change.
Notes for the ship step (not part of the PR body)
MINOR:because there is no filed GitHub issue. This is explicitlysanctioned by
.github/PULL_REQUEST_TEMPLATE.md("or simply use the title belowif it is a minor issue: MINOR: ${SUMMARY}") and matches recent master history
(e.g. "MINOR: Fix error message in SimpleGroup.add() for binary (MINOR: Fix error message in SimpleGroup.add() for Binary #3385)").
issue to close.
origin/masterright before pushing if upstream has advanced.patch-1is justa placeholder):
fix/primitivestringifier-javadoc-link.