diff --git a/core/java/android/text/style/ReplacementSpan.java b/core/java/android/text/style/ReplacementSpan.java
index 26c725faed151..07190b2f1d6ab 100644
--- a/core/java/android/text/style/ReplacementSpan.java
+++ b/core/java/android/text/style/ReplacementSpan.java
@@ -16,18 +16,49 @@
 
 package android.text.style;
 
+import android.annotation.IntRange;
+import android.annotation.NonNull;
+import android.annotation.Nullable;
 import android.graphics.Paint;
 import android.graphics.Canvas;
 import android.text.TextPaint;
 
 public abstract class ReplacementSpan extends MetricAffectingSpan {
 
-    public abstract int getSize(Paint paint, CharSequence text,
-                         int start, int end,
-                         Paint.FontMetricsInt fm);
-    public abstract void draw(Canvas canvas, CharSequence text,
-                     int start, int end, float x,
-                     int top, int y, int bottom, Paint paint);
+    /**
+     * Returns the width of the span. Extending classes can set the height of the span by updating
+     * attributes of {@link android.graphics.Paint.FontMetricsInt}. If the span covers the whole
+     * text, and the height is not set,
+     * {@link #draw(Canvas, CharSequence, int, int, float, int, int, int, Paint)} will not be
+     * called for the span.
+     *
+     * @param paint Paint instance.
+     * @param text Current text.
+     * @param start Start character index for span.
+     * @param end End character index for span.
+     * @param fm Font metrics, can be null.
+     * @return Width of the span.
+     */
+    public abstract int getSize(@NonNull Paint paint, CharSequence text,
+                        @IntRange(from = 0) int start, @IntRange(from = 0) int end,
+                        @Nullable Paint.FontMetricsInt fm);
+
+    /**
+     * Draws the span into the canvas.
+     *
+     * @param canvas Canvas into which the span should be rendered.
+     * @param text Current text.
+     * @param start Start character index for span.
+     * @param end End character index for span.
+     * @param x Edge of the replacement closest to the leading margin.
+     * @param top Top of the line.
+     * @param y Baseline.
+     * @param bottom Bottom of the line.
+     * @param paint Paint instance.
+     */
+    public abstract void draw(@NonNull Canvas canvas, CharSequence text,
+                              @IntRange(from = 0) int start, @IntRange(from = 0) int end, float x,
+                              int top, int y, int bottom, @NonNull Paint paint);
 
     /**
      * This method does nothing, since ReplacementSpans are measured