Make suggested edits and take a pass over the markdown from 5216a43

PiperOrigin-RevId: 834323965

Author: graememorgan

core/src/main/java/com/google/errorprone/bugpatterns/UnsafeLocaleUsage.java

@@ -50,7 +50,7 @@ public final class UnsafeLocaleUsage extends BugChecker
   private static final Matcher<ExpressionTree> LOCALE_CONSTRUCTOR =
       constructor().forClass("java.util.Locale");
 
-  // Used for both Locale constructors and Locale.of static methods.
+  /** Used for both Locale constructors and Locale.of static methods. */
   private static final String DESCRIPTION =
       " They do not check their arguments for"
           + " well-formedness. Prefer using Locale.forLanguageTag(String)"
@@ -96,7 +96,7 @@ public Description matchNewClass(NewClassTree tree, VisitorState state) {
     return Description.NO_MATCH;
   }
 
-  // Something that can be called with arguments, for example a method or constructor.
+  /** Something that can be called with arguments, for example a method or constructor. */
   private static void fixCallableWithArguments(
       Description.Builder descriptionBuilder,
       ImmutableList<? extends ExpressionTree> arguments,

docs/bugpattern/UnsafeLocaleUsage.md

@@ -4,8 +4,7 @@ examples of error prone issues below:
 #### Constructors
 
 The constructors don't validate the parameters at all, they just "trust" it
-100%. \
-This is also true for the static method `Locale.of`, introduced in JDK 19.
+100%. This is also true for the static method `Locale.of`, introduced in JDK 19.
 
 For example:
 
@@ -49,10 +48,9 @@ getVariant()  :
 We can see that while the `toString()` value for both locales are equivalent,
 the individual parts are different. More specifically, the first locale is
 incorrect since `#Hant` is supposed to be the script for the locale rather than
-the variant. \
-There's no reliable way of getting a correct result through a `Locale`
-constructor, so we should prefer using `Locale.forLanguageTag()` (and the IETF
-BCP 47 format) for correctness.
+the variant. There's no reliable way of getting a correct result through a
+`Locale` constructor, so we should prefer using `Locale.forLanguageTag()` (and
+the IETF BCP 47 format) for correctness.
 
 **Note:** You might see a `.replace('_', '-')` appended to a suggested fix for
 the error prone checker for this bug pattern. This is sanitization measure to
@@ -68,7 +66,6 @@ If the initial code started with a `String` that was split at `'_'` or `'-'`,
 just to be used for locale, the right fix is to use `toLanguageTag()`.
 
 ```java
-// Initial code
 void someMethod(String localeId) {
   String[] parts = localeId.split("_");
   Locale locale = switch (parts.size) {
@@ -78,10 +75,11 @@ void someMethod(String localeId) {
   }
   // use the locale
 }
+```
 
-// Fixed code
+```java
 void someMethod(String localeId) {
-  Locale locale = Locale.forLanguageTag.replace('_', '-');
+  Locale locale = Locale.forLanguageTag(localeId.replace('_', '-'));
   // use the locale
 }
 ```
@@ -90,15 +88,15 @@ If the initial code started separate "pieces" (language, region, variant) the
 right fix is to use a `Locale.Builder()`.
 
 ```java
-// Initial code
 void someMethod(@NotNull String langId, String regionId) {
   Locale locale (regionId == null)
       ? new Locale(langId) // or Locale.of
       : new Locale(langId, regionId); // or Locale.of
   // use the locale
 }
+```
 
-// Fixed code
+```java
 void someMethod(@NotNull String langId, String regionId) {
   Locale.Builder builder = new Locale.Builder();
   builder.setLanguage(langId);
@@ -110,7 +108,7 @@ void someMethod(@NotNull String langId, String regionId) {
 }
 ```
 
-#### toString()
+#### `toString()`
 
 This poses the inverse of the constructor problem.
 
@@ -121,11 +119,10 @@ Locale derivedLocale = ??? // Not clean way to get a correct locale from myLocal
 ```
 
 The `toString()` implementation for `Locale` isn't necessarily incorrect in
-itself. \
-It is intended to be _"concise but informative representation that is easy for a
-person to read"_ (see documentation at
+itself. It is intended to be *"concise but informative representation that is
+easy for a person to read"* (see documentation at
 [Object.toString()](https://docs.oracle.com/javase/6/docs/api/java/lang/Object.html#toString\(\))).
 
 So it is not intended to produce a value that can be turned back into a
-`Locale`. It is not a serialization format. \
-It often produces a value that _looks_ like a locale identifier, but it is not.
+`Locale`. It is not a serialization format. It often produces a value that
+*looks* like a locale identifier, but it is not.