diff --git a/core/java/android/os/Vibrator.java b/core/java/android/os/Vibrator.java
index 097b67259c4b5..75bc8af6efb1a 100644
--- a/core/java/android/os/Vibrator.java
+++ b/core/java/android/os/Vibrator.java
@@ -228,6 +228,8 @@ public abstract class Vibrator {
     /**
      * Vibrate constantly for the specified period of time.
      *
+     * <p>The app should be in foreground for the vibration to happen.</p>
+     *
      * @param milliseconds The number of milliseconds to vibrate.
      * @deprecated Use {@link #vibrate(VibrationEffect)} instead.
      */
@@ -240,6 +242,9 @@ public abstract class Vibrator {
     /**
      * Vibrate constantly for the specified period of time.
      *
+     * <p>The app should be in foreground for the vibration to happen. Background apps should
+     * specify a ringtone, notification or alarm usage in order to vibrate.</p>
+     *
      * @param milliseconds The number of milliseconds to vibrate.
      * @param attributes   {@link AudioAttributes} corresponding to the vibration. For example,
      *                     specify {@link AudioAttributes#USAGE_ALARM} for alarm vibrations or
@@ -274,6 +279,8 @@ public abstract class Vibrator {
      * to start the repeat, or -1 to disable repeating.
      * </p>
      *
+     * <p>The app should be in foreground for the vibration to happen.</p>
+     *
      * @param pattern an array of longs of times for which to turn the vibrator on or off.
      * @param repeat  the index into pattern at which to repeat, or -1 if
      *                you don't want to repeat.
@@ -299,6 +306,9 @@ public abstract class Vibrator {
      * to start the repeat, or -1 to disable repeating.
      * </p>
      *
+     * <p>The app should be in foreground for the vibration to happen. Background apps should
+     * specify a ringtone, notification or alarm usage in order to vibrate.</p>
+     *
      * @param pattern    an array of longs of times for which to turn the vibrator on or off.
      * @param repeat     the index into pattern at which to repeat, or -1 if
      *                   you don't want to repeat.
@@ -326,11 +336,30 @@ public abstract class Vibrator {
         }
     }
 
+    /**
+     * Vibrate with a given effect.
+     *
+     * <p>The app should be in foreground for the vibration to happen.</p>
+     *
+     * @param vibe {@link VibrationEffect} describing the vibration to be performed.
+     */
     @RequiresPermission(android.Manifest.permission.VIBRATE)
     public void vibrate(VibrationEffect vibe) {
         vibrate(vibe, null);
     }
 
+    /**
+     * Vibrate with a given effect.
+     *
+     * <p>The app should be in foreground for the vibration to happen. Background apps should
+     * specify a ringtone, notification or alarm usage in order to vibrate.</p>
+     *
+     * @param vibe       {@link VibrationEffect} describing the vibration to be performed.
+     * @param attributes {@link AudioAttributes} corresponding to the vibration. For example,
+     *                   specify {@link AudioAttributes#USAGE_ALARM} for alarm vibrations or
+     *                   {@link AudioAttributes#USAGE_NOTIFICATION_RINGTONE} for
+     *                   vibrations associated with incoming calls.
+     */
     @RequiresPermission(android.Manifest.permission.VIBRATE)
     public void vibrate(VibrationEffect vibe, AudioAttributes attributes) {
         vibrate(Process.myUid(), mPackageName, vibe, null, attributes);