Merge "docs: Edited API documentation related to line-break and line-break word styles."

3 files changed, 86 insertions, 65 deletions

diff --git a/core/java/android/widget/TextView.java b/core/java/android/widget/TextView.java
index 3f87ec2beae5..c6ac0382fa32 100644
--- a/core/java/android/widget/TextView.java
+++ b/core/java/android/widget/TextView.java
@@ -4887,20 +4887,28 @@ public class TextView extends View implements ViewTreeObserver.OnPreDrawListener
     }
 
     /**
-     * Set the line break style for text wrapping.
+     * Sets the line-break style for text wrapping.
      *
-     * The line break style to indicates the line break strategies can be used when
-     * calculating the text wrapping. The line break style affects rule-based breaking. It
-     * specifies the strictness of line-breaking rules.
-     * There are several types for the line break style:
-     * {@link LineBreakConfig#LINE_BREAK_STYLE_LOOSE},
-     * {@link LineBreakConfig#LINE_BREAK_STYLE_NORMAL} and
-     * {@link LineBreakConfig#LINE_BREAK_STYLE_STRICT}. The default values of the line break style
-     * is {@link LineBreakConfig#LINE_BREAK_STYLE_NONE}, indicating no breaking rule is specified.
-     * See <a href="https://www.w3.org/TR/css-text-3/#line-break-property">
-     *         the line-break property</a>
+     * <p>Line-break style specifies the line-break strategies that can be used
+     * for text wrapping. The line-break style affects rule-based line breaking
+     * by specifying the strictness of line-breaking rules.</p>
      *
-     * @param lineBreakStyle the line break style for the text.
+     * <p>The following are types of line-break styles:</p>
+     * <ul>
+     *   <li>{@link LineBreakConfig#LINE_BREAK_STYLE_LOOSE}</li>
+     *   <li>{@link LineBreakConfig#LINE_BREAK_STYLE_NORMAL}</li>
+     *   <li>{@link LineBreakConfig#LINE_BREAK_STYLE_STRICT}</li>
+     * </ul>
+     *
+     * <p>The default line-break style is
+     * {@link LineBreakConfig#LINE_BREAK_STYLE_NONE}, which specifies that no
+     * line-breaking rules are used.</p>
+     *
+     * <p>See the
+     * <a href="https://www.w3.org/TR/css-text-3/#line-break-property" class="external">
+     * line-break property</a> for more information.</p>
+     *
+     * @param lineBreakStyle The line break style for the text.
      */
     public void setLineBreakStyle(@LineBreakConfig.LineBreakStyle int lineBreakStyle) {
         if (mLineBreakStyle != lineBreakStyle) {
@@ -4914,17 +4922,22 @@ public class TextView extends View implements ViewTreeObserver.OnPreDrawListener
     }
 
     /**
-     * Set the line break word style for text wrapping.
+     * Sets the line-break word style for text wrapping.
+     *
+     * <p>The line-break word style affects dictionary-based line breaking by
+     * providing phrase-based line-breaking opportunities. Use
+     * {@link LineBreakConfig#LINE_BREAK_WORD_STYLE_PHRASE} to specify
+     * phrase-based line breaking.</p>
+     *
+     * <p>The default line-break word style is
+     * {@link LineBreakConfig#LINE_BREAK_WORD_STYLE_NONE}, which specifies that
+     * no line-breaking word style is used.</p>
      *
-     * The line break word style affects dictionary-based breaking and provide phrase-based
-     * breaking opportunities. The type for the line break word style is
-     * {@link LineBreakConfig#LINE_BREAK_WORD_STYLE_PHRASE}. The default values of the line break
-     * word style is {@link LineBreakConfig#LINE_BREAK_WORD_STYLE_NONE}, indicating no breaking rule
-     * is specified.
-     * See <a href="https://www.w3.org/TR/css-text-3/#word-break-property">
-     *         the word-break property</a>
+     * <p>See the
+     * <a href="https://www.w3.org/TR/css-text-3/#word-break-property" class="external">
+     * word-break property</a> for more information.</p>
      *
-     * @param lineBreakWordStyle the line break word style for the tet
+     * @param lineBreakWordStyle The line break word style for the text.
      */
     public void setLineBreakWordStyle(@LineBreakConfig.LineBreakWordStyle int lineBreakWordStyle) {
         mUserSpeficiedLineBreakwordStyle = true;
@@ -4939,18 +4952,18 @@ public class TextView extends View implements ViewTreeObserver.OnPreDrawListener
     }
 
     /**
-     * Get the current line break style for text wrapping.
+     * Gets the current line-break style for text wrapping.
      *
-     * @return the current line break style to be used for text wrapping.
+     * @return The line-break style to be used for text wrapping.
      */
     public @LineBreakConfig.LineBreakStyle int getLineBreakStyle() {
         return mLineBreakStyle;
     }
 
     /**
-     * Get the current line word break style for text wrapping.
+     * Gets the current line-break word style for text wrapping.
      *
-     * @return the current line break word style to be used for text wrapping.
+     * @return The line-break word style to be used for text wrapping.
      */
     public @LineBreakConfig.LineBreakWordStyle int getLineBreakWordStyle() {
         return mLineBreakWordStyle;
diff --git a/core/res/res/values/attrs.xml b/core/res/res/values/attrs.xml
index d43a6c59a477..c7153fcf8609 100644
--- a/core/res/res/values/attrs.xml
+++ b/core/res/res/values/attrs.xml
@@ -5542,22 +5542,22 @@
              ignores some hyphen character related typographic features, e.g. kerning. -->
             <enum name="fullFast" value="4" />
         </attr>
-        <!-- Indicates the line break strategies can be used when calculating the text wrapping. -->
+        <!-- Specifies the line-break strategies for text wrapping. -->
         <attr name="lineBreakStyle">
-            <!-- No line break style specific. -->
+            <!-- No line-break rules are used for line breaking. -->
             <enum name="none" value="0" />
-            <!-- Use the least restrictive rule for line-breaking. -->
+            <!-- The least restrictive line-break rules are used for line breaking. -->
             <enum name="loose" value="1" />
-            <!-- Indicates breaking text with the most comment set of line-breaking rules. -->
+            <!-- The most common line-break rules are used for line breaking. -->
             <enum name="normal" value="2" />
-            <!-- Indicates breaking text with the most strictest line-breaking rules. -->
+            <!-- The most strict line-break rules are used for line breaking. -->
             <enum name="strict" value="3" />
         </attr>
-        <!-- Specify the phrase-based line break can be used when calculating the text wrapping.-->
+        <!-- Specifies the line-break word strategies for text wrapping.-->
         <attr name="lineBreakWordStyle">
-            <!-- No line break word style specific. -->
+            <!-- No line-break word style is used for line breaking. -->
             <enum name="none" value="0" />
-            <!-- Specify the phrase based breaking. -->
+            <!-- Line breaking is based on phrases, which results in text wrapping only on meaningful words. -->
             <enum name="phrase" value="1" />
         </attr>
         <!-- Specify the type of auto-size. Note that this feature is not supported by EditText,
diff --git a/graphics/java/android/graphics/text/LineBreakConfig.java b/graphics/java/android/graphics/text/LineBreakConfig.java
index 7ad9aecaf6a3..48aecd61fc19 100644
--- a/graphics/java/android/graphics/text/LineBreakConfig.java
+++ b/graphics/java/android/graphics/text/LineBreakConfig.java
@@ -24,29 +24,32 @@ import java.lang.annotation.RetentionPolicy;
 import java.util.Objects;
 
 /**
- * Indicates the strategies can be used when calculating the text wrapping.
+ * Specifies the line-break strategies for text wrapping.
  *
- * See <a href="https://www.w3.org/TR/css-text-3/#line-break-property">the line-break property</a>
+ * <p>See the
+ * <a href="https://www.w3.org/TR/css-text-3/#line-break-property" class="external">
+ * line-break property</a> for more information.</p>
  */
 public final class LineBreakConfig {
 
     /**
-     * No line break style specified.
+     * No line-break rules are used for line breaking.
      */
     public static final int LINE_BREAK_STYLE_NONE = 0;
 
     /**
-     * Use the least restrictive rule for line-breaking. This is usually used for short lines.
+     * The least restrictive line-break rules are used for line breaking. This
+     * setting is typically used for short lines.
      */
     public static final int LINE_BREAK_STYLE_LOOSE = 1;
 
     /**
-     * Indicate breaking text with the most comment set of line-breaking rules.
+     * The most common line-break rules are used for line breaking.
      */
     public static final int LINE_BREAK_STYLE_NORMAL = 2;
 
     /**
-     * Indicates breaking text with the most strictest line-breaking rules.
+     * The most strict line-break rules are used for line breaking.
      */
     public static final int LINE_BREAK_STYLE_STRICT = 3;
 
@@ -59,15 +62,17 @@ public final class LineBreakConfig {
     public @interface LineBreakStyle {}
 
     /**
-     * No line break word style specified.
+     * No line-break word style is used for line breaking.
      */
     public static final int LINE_BREAK_WORD_STYLE_NONE = 0;
 
     /**
-     * Indicates the line breaking is based on the phrased. This makes text wrapping only on
-     * meaningful words. The support of the text wrapping word style varies depending on the
-     * locales. If the locale does not support the phrase based text wrapping,
-     * there will be no effect.
+     * Line breaking is based on phrases, which results in text wrapping only on
+     * meaningful words.
+     *
+     * <p>Support for this line-break word style depends on locale. If the
+     * current locale does not support phrase-based text wrapping, this setting
+     * has no effect.</p>
      */
     public static final int LINE_BREAK_WORD_STYLE_PHRASE = 1;
 
@@ -79,7 +84,7 @@ public final class LineBreakConfig {
     public @interface LineBreakWordStyle {}
 
     /**
-     * A builder for creating {@link LineBreakConfig}.
+     * A builder for creating a {@code LineBreakConfig} instance.
      */
     public static final class Builder {
         // The line break style for the LineBreakConfig.
@@ -95,16 +100,16 @@ public final class LineBreakConfig {
         private boolean mAutoPhraseBreaking = false;
 
         /**
-         * Builder constructor with line break parameters.
+         * Builder constructor.
          */
         public Builder() {
         }
 
         /**
-         * Set the line break style.
+         * Sets the line-break style.
          *
-         * @param lineBreakStyle the new line break style.
-         * @return this Builder
+         * @param lineBreakStyle The new line-break style.
+         * @return This {@code Builder}.
          */
         public @NonNull Builder setLineBreakStyle(@LineBreakStyle int lineBreakStyle) {
             mLineBreakStyle = lineBreakStyle;
@@ -112,10 +117,10 @@ public final class LineBreakConfig {
         }
 
         /**
-         * Set the line break word style.
+         * Sets the line-break word style.
          *
-         * @param lineBreakWordStyle the new line break word style.
-         * @return this Builder
+         * @param lineBreakWordStyle The new line-break word style.
+         * @return This {@code Builder}.
          */
         public @NonNull Builder setLineBreakWordStyle(@LineBreakWordStyle int lineBreakWordStyle) {
             mLineBreakWordStyle = lineBreakWordStyle;
@@ -123,7 +128,7 @@ public final class LineBreakConfig {
         }
 
         /**
-         * Enable or disable the automation of {@link LINE_BREAK_WORD_STYLE_PHRASE}.
+         * Enables or disables the automation of {@link LINE_BREAK_WORD_STYLE_PHRASE}.
          *
          * @hide
          */
@@ -133,9 +138,9 @@ public final class LineBreakConfig {
         }
 
         /**
-         * Build the {@link LineBreakConfig}
+         * Builds a {@link LineBreakConfig} instance.
          *
-         * @return the LineBreakConfig instance.
+         * @return The {@code LineBreakConfig} instance.
          */
         public @NonNull LineBreakConfig build() {
             return new LineBreakConfig(mLineBreakStyle, mLineBreakWordStyle, mAutoPhraseBreaking);
@@ -143,11 +148,12 @@ public final class LineBreakConfig {
     }
 
     /**
-     * Create the LineBreakConfig instance.
+     * Creates a {@code LineBreakConfig} instance with the provided line break
+     * parameters.
      *
-     * @param lineBreakStyle the line break style for text wrapping.
-     * @param lineBreakWordStyle the line break word style for text wrapping.
-     * @return the {@link LineBreakConfig} instance.
+     * @param lineBreakStyle The line-break style for text wrapping.
+     * @param lineBreakWordStyle The line-break word style for text wrapping.
+     * @return The {@code LineBreakConfig} instance.
      * @hide
      */
     public static @NonNull LineBreakConfig getLineBreakConfig(@LineBreakStyle int lineBreakStyle,
@@ -185,8 +191,10 @@ public final class LineBreakConfig {
     private final boolean mAutoPhraseBreaking;
 
     /**
-     * Constructor with the line break parameters.
-     * Use the {@link LineBreakConfig.Builder} to create the LineBreakConfig instance.
+     * Constructor with line-break parameters.
+     *
+     * <p>Use {@link LineBreakConfig.Builder} to create the
+     * {@code LineBreakConfig} instance.</p>
      */
     private LineBreakConfig(@LineBreakStyle int lineBreakStyle,
             @LineBreakWordStyle int lineBreakWordStyle, boolean autoPhraseBreaking) {
@@ -196,18 +204,18 @@ public final class LineBreakConfig {
     }
 
     /**
-     * Get the line break style.
+     * Gets the current line-break style.
      *
-     * @return The current line break style to be used for the text wrapping.
+     * @return The line-break style to be used for text wrapping.
      */
     public @LineBreakStyle int getLineBreakStyle() {
         return mLineBreakStyle;
     }
 
     /**
-     * Get the line break word style.
+     * Gets the current line-break word style.
      *
-     * @return The current line break word style to be used for the text wrapping.
+     * @return The line-break word style to be used for text wrapping.
      */
     public @LineBreakWordStyle int getLineBreakWordStyle() {
         return mLineBreakWordStyle;