8303275: Use {@Return and @linkplain in Locale and related classes #12780

justin-curtis-lu · 2023-02-28T00:09:45Z

This PR modifies the javadoc of methods in Locale, LocaleServiceProvider, and LocaleServiceProviderPool to use {@return and @linkplain.

Progress

Change must be properly reviewed (1 review required, with at least 1 Reviewer)
Change must not contain extraneous whitespace
Commit message must refer to an issue

Issue

JDK-8303275: Use {@return and @linkplain in Locale and related classes

Reviewers

Naoto Sato (@naotoj - Reviewer)

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.org/jdk pull/12780/head:pull/12780
$ git checkout pull/12780

Update a local copy of the PR:
$ git checkout pull/12780
$ git pull https://git.openjdk.org/jdk pull/12780/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 12780

View PR using the GUI difftool:
$ git pr show -t 12780

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/jdk/pull/12780.diff

bridgekeeper · 2023-02-28T00:10:40Z

👋 Welcome back jlu! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

openjdk · 2023-02-28T00:12:12Z

@justin-curtis-lu The following labels will be automatically applied to this pull request:

core-libs
i18n

When this pull request is ready to be reviewed, an "RFR" email will be sent to the corresponding mailing lists. If you would like to change these labels, use the /label pull request command.

justin-curtis-lu · 2023-03-01T18:13:05Z

src/java.base/share/classes/java/util/Locale.java

@@ -1237,12 +1236,11 @@ public static String[] getISOCountries() {
    }

    /**
-     * Returns a {@code Set} of ISO3166 country codes for the specified type.
+     * {@return a {@code Set} of ISO3166 country codes for the specified type}


This and other instances will have the Returns ... and @return ... differ by a single word. Such as

Returns a {@code Set} of ISO3166 country...
vs
@return a {@code Set} of ISO country...

{@return is used when the Returns ... and @return ... are identical.

I want to double check that using {@return for these instances is acceptable (even though they are technically not identical), if not I can revert them.

justin-curtis-lu · 2023-03-01T18:13:27Z

src/java.base/share/classes/java/util/Locale.java

@@ -1196,15 +1197,13 @@ public static synchronized void setDefault(Locale.Category category,
    }

    /**
-     * Returns an array of all installed locales.
+     * {@return an array of installed locales}


Same as above, differs with "all"

justin-curtis-lu · 2023-03-01T18:14:42Z

src/java.base/share/classes/sun/util/locale/provider/LocaleServiceProviderPool.java

@@ -148,22 +148,21 @@ private AllAvailableLocales() {
    }

    /**
-     * Returns an array of available locales for all the provider classes.
+     * {@return an array of the available locales for all the provider classes}


Same as above, differs with "the"

justin-curtis-lu · 2023-03-01T18:14:51Z

src/java.base/share/classes/sun/util/locale/provider/LocaleServiceProviderPool.java

     */
    public static Locale[] getAllAvailableLocales() {
        return AllAvailableLocales.allAvailableLocales.clone();
    }

    /**
-     * Returns an array of available locales.  This array is a
+     * {@return an array of the available locales}


Same as above, differs with "the"

mlbridge · 2023-03-01T22:03:56Z

Webrevs

01: Full - Incremental (5850ca02)
00: Full (cfbbfa0a)

naotoj · 2023-03-02T16:43:47Z

src/java.base/share/classes/java/util/Locale.java

@@ -2074,7 +2072,7 @@ public String getDisplayVariant(Locale inLocale) {
     * Returns a name for the locale that is appropriate for display to the
     * user. This will be the values returned by getDisplayLanguage(),
     * getDisplayScript(), getDisplayCountry(), getDisplayVariant() and
-     * optional <a href="./Locale.html#def_locale_extension">Unicode extensions</a>
+     * optional {@linkplain Locale##def_locale_extension Unicode extensions}


Can Locale be removed? It seems redundant. There are other locations with the same situation in this class.

Yes, removed this and the other instances of @linkplain that use the Locale prefix. I left the ones in Locale.Builder and Locale.LanguageRange since they are generated with different html pages and need the Locale link.

openjdk · 2023-03-02T20:23:06Z

@justin-curtis-lu This change now passes all automated pre-integration checks.

ℹ️ This project also has non-automated pre-integration requirements. Please see the file CONTRIBUTING.md for details.

After integration, the commit message for the final commit will be:

8303275: Use {@Return and @linkplain in Locale and related classes

Reviewed-by: naoto

You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed.

At the time when this comment was updated there had been 78 new commits pushed to the master branch:

ac3ab5b: 8217496: Matcher.group() can return null after usePattern
45a616a: 8303480: Miscellaneous fixes to mostly invisible doc comments
43288bb: 8301477: Replace NULL with nullptr in os/aix
008c5eb: 8303621: BitMap::iterate should support lambdas and other function objects
52d3008: 8303497: [s390x] ProblemList TestUnreachableInnerLoop.java
3f2d929: 8303511: C2: assert(get_ctrl(n) == cle_out) during unrolling
7fbfc88: 8303534: Merge CompactibleSpace into ContiguousSpace
97c25df: 8204550: NMT: RegionIterator does not need to keep _current_size
94eda53: 8201516: DebugNonSafepoints generates incorrect information
c51d40c: 8303607: SunMSCAPI provider leaks memory and keys
... and 68 more: https://git.openjdk.org/jdk/compare/9fc518ff8cadbbb731a016d8f53ed065b3561a7c...master

As there are no conflicts, your changes will automatically be rebased on top of these commits when integrating. If you prefer to avoid this automatic rebasing, please check the documentation for the /integrate command for further details.

As you do not have Committer status in this project an existing Committer must agree to sponsor your change. Possible candidates are the reviewers of this PR (@naotoj) but any other Committer may sponsor as well.

➡️ To flag this PR as ready for integration with the above commit message, type /integrate in a new comment. (Afterwards, your sponsor types /sponsor in a new comment to perform the integration).

justin-curtis-lu · 2023-03-07T18:03:53Z

/integrate

openjdk · 2023-03-07T18:06:30Z

@justin-curtis-lu
Your change (at version 5850ca0) is now ready to be sponsored by a Committer.

naotoj · 2023-03-07T18:17:19Z

/integrate

naotoj · 2023-03-07T18:17:30Z

/sponsor

openjdk · 2023-03-07T18:18:06Z

@naotoj Only the author (@justin-curtis-lu) is allowed to issue the integrate command. As this pull request is ready to be sponsored, and you are an eligible sponsor, did you mean to issue the /sponsor command?

openjdk · 2023-03-07T18:19:07Z

Going to push as commit acf8996.
Since your change was applied there have been 78 commits pushed to the master branch:

ac3ab5b: 8217496: Matcher.group() can return null after usePattern
45a616a: 8303480: Miscellaneous fixes to mostly invisible doc comments
43288bb: 8301477: Replace NULL with nullptr in os/aix
008c5eb: 8303621: BitMap::iterate should support lambdas and other function objects
52d3008: 8303497: [s390x] ProblemList TestUnreachableInnerLoop.java
3f2d929: 8303511: C2: assert(get_ctrl(n) == cle_out) during unrolling
7fbfc88: 8303534: Merge CompactibleSpace into ContiguousSpace
97c25df: 8204550: NMT: RegionIterator does not need to keep _current_size
94eda53: 8201516: DebugNonSafepoints generates incorrect information
c51d40c: 8303607: SunMSCAPI provider leaks memory and keys
... and 68 more: https://git.openjdk.org/jdk/compare/9fc518ff8cadbbb731a016d8f53ed065b3561a7c...master

Your commit was automatically rebased without conflicts.

openjdk · 2023-03-07T18:19:23Z

@naotoj @justin-curtis-lu Pushed as commit acf8996.

💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored.

justin-curtis-lu added 4 commits February 27, 2023 14:53

Use {@return and @linkplain in LSP

87173bf

Use {@return and spacing in LSPP

8a8def3

Use @linkplain and {@return in Locale

6dfab1d

Locale copyright

cbbe655

openjdk bot added core-libs core-libs-dev@openjdk.org i18n i18n-dev@openjdk.org labels Feb 28, 2023

justin-curtis-lu commented Mar 1, 2023

View reviewed changes

fix conflicts

cfbbfa0

justin-curtis-lu marked this pull request as ready for review March 1, 2023 21:58

openjdk bot added the rfr Pull request is ready for review label Mar 1, 2023

naotoj reviewed Mar 2, 2023

View reviewed changes

Remove prefix Locale for in-class linkplains

5850ca0

naotoj approved these changes Mar 2, 2023

View reviewed changes

openjdk bot added the ready Pull request is ready to be integrated label Mar 2, 2023

openjdk bot added the sponsor Pull request is ready to be sponsored label Mar 7, 2023

openjdk bot added the integrated Pull request has been integrated label Mar 7, 2023

openjdk bot closed this Mar 7, 2023

openjdk bot removed ready Pull request is ready to be integrated rfr Pull request is ready for review sponsor Pull request is ready to be sponsored labels Mar 7, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

8303275: Use {@Return and @linkplain in Locale and related classes #12780

8303275: Use {@Return and @linkplain in Locale and related classes #12780

justin-curtis-lu commented Feb 28, 2023 •

edited by openjdk bot

Loading

bridgekeeper bot commented Feb 28, 2023

openjdk bot commented Feb 28, 2023

justin-curtis-lu Mar 1, 2023

justin-curtis-lu Mar 1, 2023

justin-curtis-lu Mar 1, 2023

justin-curtis-lu Mar 1, 2023

mlbridge bot commented Mar 1, 2023 •

edited

Loading

naotoj Mar 2, 2023

justin-curtis-lu Mar 2, 2023

openjdk bot commented Mar 2, 2023 •

edited

Loading

justin-curtis-lu commented Mar 7, 2023

openjdk bot commented Mar 7, 2023

naotoj commented Mar 7, 2023

naotoj commented Mar 7, 2023

openjdk bot commented Mar 7, 2023

openjdk bot commented Mar 7, 2023

openjdk bot commented Mar 7, 2023

8303275: Use {@Return and @linkplain in Locale and related classes #12780

8303275: Use {@Return and @linkplain in Locale and related classes #12780

Conversation

justin-curtis-lu commented Feb 28, 2023 • edited by openjdk bot Loading

Progress

Issue

Reviewers

Reviewing

bridgekeeper bot commented Feb 28, 2023

openjdk bot commented Feb 28, 2023

justin-curtis-lu Mar 1, 2023

Choose a reason for hiding this comment

justin-curtis-lu Mar 1, 2023

Choose a reason for hiding this comment

justin-curtis-lu Mar 1, 2023

Choose a reason for hiding this comment

justin-curtis-lu Mar 1, 2023

Choose a reason for hiding this comment

mlbridge bot commented Mar 1, 2023 • edited Loading

Webrevs

naotoj Mar 2, 2023

Choose a reason for hiding this comment

justin-curtis-lu Mar 2, 2023

Choose a reason for hiding this comment

openjdk bot commented Mar 2, 2023 • edited Loading

justin-curtis-lu commented Mar 7, 2023

openjdk bot commented Mar 7, 2023

naotoj commented Mar 7, 2023

naotoj commented Mar 7, 2023

openjdk bot commented Mar 7, 2023

openjdk bot commented Mar 7, 2023

openjdk bot commented Mar 7, 2023

justin-curtis-lu commented Feb 28, 2023 •

edited by openjdk bot

Loading

mlbridge bot commented Mar 1, 2023 •

edited

Loading

openjdk bot commented Mar 2, 2023 •

edited

Loading