From 447f56e5e965cec482f5eb464e81ffebebea8f44 Mon Sep 17 00:00:00 2001 From: Simon Bowden Date: Tue, 15 Feb 2022 11:50:54 +0000 Subject: [PATCH] Update vibrator javadoc formatting. After reviewing rendered docs, adding missing paragraph markers and some small typos, as well as fixing code snippets to be inside a 
 block. At the
moment, trailing newlines get picked up so it's also necessary to
terminate the code and pre blocks on the actual last line of code.

Test: built docs and manually reviewed site
Change-Id: I327b146eaae20fa3a2e8cf066e211e14cb165c51
---
 core/java/android/os/VibrationAttributes.java |  4 +-
 core/java/android/os/VibrationEffect.java     | 97 +++++++++----------
 core/java/android/os/Vibrator.java            | 28 +++---
 core/java/android/os/VibratorInfo.java        |  3 +-
 core/java/android/os/VibratorManager.java     |  2 +-
 .../os/vibrator/VibratorFrequencyProfile.java |  3 +-
 6 files changed, 66 insertions(+), 71 deletions(-)

diff --git a/core/java/android/os/VibrationAttributes.java b/core/java/android/os/VibrationAttributes.java
index d223a19b43484..642c618ba1f7c 100644
--- a/core/java/android/os/VibrationAttributes.java
+++ b/core/java/android/os/VibrationAttributes.java
@@ -27,7 +27,7 @@ import java.lang.annotation.RetentionPolicy;
 import java.util.Objects;
 
 /**
- * A class to encapsulate a collection of attributes describing information about a vibration
+ * Encapsulates a collection of attributes describing information about a vibration.
  */
 public final class VibrationAttributes implements Parcelable {
     private static final String TAG = "VibrationAttributes";
@@ -174,7 +174,7 @@ public final class VibrationAttributes implements Parcelable {
             FLAG_BYPASS_INTERRUPTION_POLICY | FLAG_BYPASS_USER_VIBRATION_INTENSITY_OFF;
 
     /** Creates a new {@link VibrationAttributes} instance with given usage. */
-    public static @NonNull VibrationAttributes createForUsage(int usage) {
+    public static @NonNull VibrationAttributes createForUsage(@Usage int usage) {
         return new VibrationAttributes.Builder().setUsage(usage).build();
     }
 
diff --git a/core/java/android/os/VibrationEffect.java b/core/java/android/os/VibrationEffect.java
index 21c64876c24c7..237f6ed819f61 100644
--- a/core/java/android/os/VibrationEffect.java
+++ b/core/java/android/os/VibrationEffect.java
@@ -48,7 +48,7 @@ import java.util.Objects;
 /**
  * A VibrationEffect describes a haptic effect to be performed by a {@link Vibrator}.
  *
- * These effects may be any number of things, from single shot vibrations to complex waveforms.
+ * 
These effects may be any number of things, from single shot vibrations to complex waveforms.
  */
 public abstract class VibrationEffect implements Parcelable {
     // Stevens' coefficient to scale the perceived vibration intensity.
@@ -110,7 +110,7 @@ public abstract class VibrationEffect implements Parcelable {
     /**
      * A texture effect meant to replicate soft ticks.
      *
-     * Unlike normal effects, texture effects are meant to be called repeatedly, generally in
+     * 
Unlike normal effects, texture effects are meant to be called repeatedly, generally in
      * response to some motion, in order to replicate the feeling of some texture underneath the
      * user's fingers.
      *
@@ -175,7 +175,7 @@ public abstract class VibrationEffect implements Parcelable {
     /**
      * Create a one shot vibration.
      *
-     * One shot vibrations will vibrate constantly for the specified period of time at the
+     * 
One shot vibrations will vibrate constantly for the specified period of time at the
      * specified amplitude, and then stop.
      *
      * @param milliseconds The number of milliseconds to vibrate. This must be a positive number.
@@ -269,13 +269,13 @@ public abstract class VibrationEffect implements Parcelable {
     /**
      * Create a predefined vibration effect.
      *
-     * Predefined effects are a set of common vibration effects that should be identical, regardless
-     * of the app they come from, in order to provide a cohesive experience for users across
-     * the entire device. They also may be custom tailored to the device hardware in order to
+     * 
Predefined effects are a set of common vibration effects that should be identical,
+     * regardless of the app they come from, in order to provide a cohesive experience for users
+     * across the entire device. They also may be custom tailored to the device hardware in order to
      * provide a better experience than you could otherwise build using the generic building
      * blocks.
      *
-     * This will fallback to a generic pattern if one exists and there does not exist a
+     * 
This will fallback to a generic pattern if one exists and there does not exist a
      * hardware-specific implementation of the effect.
      *
      * @param effectId The ID of the effect to perform:
@@ -291,13 +291,13 @@ public abstract class VibrationEffect implements Parcelable {
     /**
      * Get a predefined vibration effect.
      *
-     * Predefined effects are a set of common vibration effects that should be identical, regardless
-     * of the app they come from, in order to provide a cohesive experience for users across
-     * the entire device. They also may be custom tailored to the device hardware in order to
+     * 
Predefined effects are a set of common vibration effects that should be identical,
+     * regardless of the app they come from, in order to provide a cohesive experience for users
+     * across the entire device. They also may be custom tailored to the device hardware in order to
      * provide a better experience than you could otherwise build using the generic building
      * blocks.
      *
-     * This will fallback to a generic pattern if one exists and there does not exist a
+     * 
This will fallback to a generic pattern if one exists and there does not exist a
      * hardware-specific implementation of the effect.
      *
      * @param effectId The ID of the effect to perform:
@@ -314,16 +314,16 @@ public abstract class VibrationEffect implements Parcelable {
     /**
      * Get a predefined vibration effect.
      *
-     * Predefined effects are a set of common vibration effects that should be identical, regardless
-     * of the app they come from, in order to provide a cohesive experience for users across
-     * the entire device. They also may be custom tailored to the device hardware in order to
+     * 
Predefined effects are a set of common vibration effects that should be identical,
+     * regardless of the app they come from, in order to provide a cohesive experience for users
+     * across the entire device. They also may be custom tailored to the device hardware in order to
      * provide a better experience than you could otherwise build using the generic building
      * blocks.
      *
-     * Some effects you may only want to play if there's a hardware specific implementation because
-     * they may, for example, be too disruptive to the user without tuning. The {@code fallback}
-     * parameter allows you to decide whether you want to fallback to the generic implementation or
-     * only play if there's a tuned, hardware specific one available.
+     * 
Some effects you may only want to play if there's a hardware specific implementation
+     * because they may, for example, be too disruptive to the user without tuning. The
+     * {@code fallback} parameter allows you to decide whether you want to fallback to the generic
+     * implementation or only play if there's a tuned, hardware specific one available.
      *
      * @param effectId The ID of the effect to perform:
      *                 {@link #EFFECT_CLICK}, {@link #EFFECT_DOUBLE_CLICK}, {@link #EFFECT_TICK}
@@ -344,9 +344,9 @@ public abstract class VibrationEffect implements Parcelable {
     /**
      * Get a predefined vibration effect associated with a given URI.
      *
-     * Predefined effects are a set of common vibration effects that should be identical, regardless
-     * of the app they come from, in order to provide a cohesive experience for users across
-     * the entire device. They also may be custom tailored to the device hardware in order to
+     * 
Predefined effects are a set of common vibration effects that should be identical,
+     * regardless of the app they come from, in order to provide a cohesive experience for users
+     * across the entire device. They also may be custom tailored to the device hardware in order to
      * provide a better experience than you could otherwise build using the generic building
      * blocks.
      *
@@ -474,7 +474,7 @@ public abstract class VibrationEffect implements Parcelable {
     /**
      * Gets the estimated duration of the vibration in milliseconds.
      *
-     * For effects without a defined end (e.g. a Waveform with a non-negative repeat index), this
+     * 
For effects without a defined end (e.g. a Waveform with a non-negative repeat index), this
      * returns Long.MAX_VALUE. For effects with an unknown duration (e.g. Prebaked effects where
      * the length is device and potentially run-time dependent), this returns -1.
      *
@@ -817,28 +817,26 @@ public abstract class VibrationEffect implements Parcelable {
      * effect that grows in intensity and then dies off, with a longer rising portion for emphasis
      * and an extra tick 100ms after:
      *
-     * 
-     * VibrationEffect effect = VibrationEffect.startComposition()
+     * 
+     * {@code VibrationEffect effect = VibrationEffect.startComposition()
      *     .addPrimitive(VibrationEffect.Composition.PRIMITIVE_SLOW_RISE, 0.5f)
      *     .addPrimitive(VibrationEffect.Composition.PRIMITIVE_QUICK_FALL, 0.5f)
      *     .addPrimitive(VibrationEffect.Composition.PRIMITIVE_TICK, 1.0f, 100)
-     *     .compose();
-     * 
+     *     .compose();}

      *
      * 
Composition elements can also be {@link VibrationEffect} instances, including other
      * compositions, and off durations, which are periods of time when the vibrator will be
      * turned off. Here is an example of a composition that "warms up" with a light tap,
      * a stronger double tap, then repeats a vibration pattern indefinitely:
      *
-     * 
-     * VibrationEffect repeatingEffect = VibrationEffect.startComposition()
+     * 
+     * {@code VibrationEffect repeatingEffect = VibrationEffect.startComposition()
      *     .addPrimitive(VibrationEffect.Composition.PRIMITIVE_LOW_TICK)
      *     .addOffDuration(Duration.ofMillis(10))
      *     .addEffect(VibrationEffect.createPredefined(VibrationEffect.EFFECT_DOUBLE_CLICK))
      *     .addOffDuration(Duration.ofMillis(50))
      *     .addEffect(VibrationEffect.createWaveform(pattern, repeatIndex))
-     *     .compose();
-     * 
+     *     .compose();}

      *
      * 
When choosing to play a composed effect, you should check that individual components are
      * supported by the device by using the appropriate vibrator method:
@@ -932,7 +930,7 @@ public abstract class VibrationEffect implements Parcelable {
 
         /**
          * Adds a time duration to the current composition, during which the vibrator will be
-         * turned off
+         * turned off.
          *
          * @param duration The length of time the vibrator should be off. Value must be non-negative
          *                 and will be truncated to milliseconds.
@@ -1004,7 +1002,7 @@ public abstract class VibrationEffect implements Parcelable {
         /**
          * Add a haptic primitive to the end of the current composition.
          *
-         * Similar to {@link #addPrimitive(int, float, int)}, but with no delay and a
+         * 
Similar to {@link #addPrimitive(int, float, int)}, but with no delay and a
          * default scale applied.
          *
          * @param primitiveId The primitive to add
@@ -1021,7 +1019,7 @@ public abstract class VibrationEffect implements Parcelable {
         /**
          * Add a haptic primitive to the end of the current composition.
          *
-         * Similar to {@link #addPrimitive(int, float, int)}, but with no delay.
+         * 
Similar to {@link #addPrimitive(int, float, int)}, but with no delay.
          *
          * @param primitiveId The primitive to add
          * @param scale The scale to apply to the intensity of the primitive.
@@ -1081,9 +1079,9 @@ public abstract class VibrationEffect implements Parcelable {
         /**
          * Compose all of the added primitives together into a single {@link VibrationEffect}.
          *
-         * The {@link Composition} object is still valid after this call, so you can continue adding
-         * more primitives to it and generating more {@link VibrationEffect}s by calling this method
-         * again.
+         * 
The {@link Composition} object is still valid after this call, so you can continue
+         * adding more primitives to it and generating more {@link VibrationEffect}s by calling this
+         * method again.
          *
          * @return The {@link VibrationEffect} resulting from the composition of the primitives.
          */
@@ -1099,7 +1097,7 @@ public abstract class VibrationEffect implements Parcelable {
         }
 
         /**
-         * Convert the primitive ID to a human readable string for debugging
+         * Convert the primitive ID to a human readable string for debugging.
          * @param id The ID to convert
          * @return The ID in a human readable format.
          * @hide
@@ -1139,16 +1137,15 @@ public abstract class VibrationEffect implements Parcelable {
      * 
The following example ramps a vibrator turned off to full amplitude at 120Hz, over 100ms
      * starting at 60Hz, then holds that state for 200ms and ramps back down again over 100ms:
      *
-     * 
-     * import static android.os.VibrationEffect.VibrationParameter.targetAmplitude;
+     * 
+     * {@code import static android.os.VibrationEffect.VibrationParameter.targetAmplitude;
      * import static android.os.VibrationEffect.VibrationParameter.targetFrequency;
      *
      * VibrationEffect effect = VibrationEffect.startWaveform(targetFrequency(60))
      *     .addTransition(Duration.ofMillis(100), targetAmplitude(1), targetFrequency(120))
      *     .addSustain(Duration.ofMillis(200))
      *     .addTransition(Duration.ofMillis(100), targetAmplitude(0), targetFrequency(60))
-     *     .build();
-     * 
+     *     .build();}

      *
      * 
The initial state of the waveform can be set via
      * {@link VibrationEffect#startWaveform(VibrationParameter)} or
@@ -1169,8 +1166,8 @@ public abstract class VibrationEffect implements Parcelable {
      * a {@link VibrationEffect.Composition}. The resulting effect will have a tick followed by a
      * repeated beating effect with a rise that stretches out and a sharp finish.
      *
-     * 
-     * VibrationEffect patternToBeRepeated = VibrationEffect.startWaveform(targetAmplitude(0.2f))
+     * 
+     * {@code VibrationEffect patternToRepeat = VibrationEffect.startWaveform(targetAmplitude(0.2f))
      *     .addSustain(Duration.ofMillis(10))
      *     .addTransition(Duration.ofMillis(20), targetAmplitude(0.4f))
      *     .addSustain(Duration.ofMillis(30))
@@ -1182,16 +1179,15 @@ public abstract class VibrationEffect implements Parcelable {
      * VibrationEffect effect = VibrationEffect.startComposition()
      *     .addPrimitive(VibrationEffect.Composition.PRIMITIVE_TICK)
      *     .addOffDuration(Duration.ofMillis(20))
-     *     .repeatEffectIndefinitely(patternToBeRepeated)
-     *     .compose();
-     * 
+     *     .repeatEffectIndefinitely(patternToRepeat)
+     *     .compose();}

      *
      * 
The amplitude step waveforms that can be created via
      * {@link VibrationEffect#createWaveform(long[], int[], int)} can also be created with
      * {@link WaveformBuilder} by adding zero duration transitions:
      *
-     * 
-     * // These two effects are the same
+     * 
+     * {@code // These two effects are the same
      * VibrationEffect waveform = VibrationEffect.createWaveform(
      *     new long[] { 10, 20, 30 },  // timings in milliseconds
      *     new int[] { 51, 102, 204 }, // amplitudes in [0,255]
@@ -1203,8 +1199,7 @@ public abstract class VibrationEffect implements Parcelable {
      *     .addSustain(Duration.ofMillis(20))
      *     .addTransition(Duration.ZERO, targetAmplitude(0.8f))
      *     .addSustain(Duration.ofMillis(30))
-     *     .build();
-     * 
+     *     .build();}

      *
      * @see VibrationEffect#startWaveform
      */
@@ -1307,7 +1302,7 @@ public abstract class VibrationEffect implements Parcelable {
         /**
          * Build the waveform as a single {@link VibrationEffect}.
          *
-         * The {@link WaveformBuilder} object is still valid after this call, so you can
+         * 
The {@link WaveformBuilder} object is still valid after this call, so you can
          * continue adding more primitives to it and generating more {@link VibrationEffect}s by
          * calling this method again.
          *
diff --git a/core/java/android/os/Vibrator.java b/core/java/android/os/Vibrator.java
index 78f1cb12ded63..7f0d6349f57fd 100644
--- a/core/java/android/os/Vibrator.java
+++ b/core/java/android/os/Vibrator.java
@@ -83,7 +83,7 @@ public abstract class Vibrator {
     /**
      * Vibration effect support: unknown
      *
-     * The hardware doesn't report it's supported effects, so we can't determine whether the
+     * 
The hardware doesn't report its supported effects, so we can't determine whether the
      * effect is supported or not.
      */
     public static final int VIBRATION_EFFECT_SUPPORT_UNKNOWN = 0;
@@ -91,14 +91,14 @@ public abstract class Vibrator {
     /**
      * Vibration effect support: supported
      *
-     * This effect is supported by the underlying hardware.
+     * 
This effect is supported by the underlying hardware.
      */
     public static final int VIBRATION_EFFECT_SUPPORT_YES = 1;
 
     /**
      * Vibration effect support: unsupported
      *
-     * This effect is not natively supported by the underlying hardware, although
+     * 
This effect is not natively supported by the underlying hardware, although
      * the system may still play a fallback vibration.
      */
     public static final int VIBRATION_EFFECT_SUPPORT_NO = 2;
@@ -317,7 +317,7 @@ public abstract class Vibrator {
     /**
      * Vibrate constantly for the specified period of time.
      *
-     * 
The app should be in foreground for the vibration to happen.

+     * 
The app should be in the foreground for the vibration to happen.

      *
      * @param milliseconds The number of milliseconds to vibrate.
      * @deprecated Use {@link #vibrate(VibrationEffect)} instead.
@@ -331,7 +331,7 @@ public abstract class Vibrator {
     /**
      * Vibrate constantly for the specified period of time.
      *
-     * 
The app should be in foreground for the vibration to happen. Background apps should
+     * 
The app should be in the foreground for the vibration to happen. Background apps should
      * specify a ringtone, notification or alarm usage in order to vibrate.

      *
      * @param milliseconds The number of milliseconds to vibrate.
@@ -368,7 +368,7 @@ public abstract class Vibrator {
      * to start the repeat, or -1 to disable repeating.
      * 

      *
-     * 
The app should be in foreground for the vibration to happen.

+     * 
The app should be in the foreground for the vibration to happen.

      *
      * @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
@@ -395,7 +395,7 @@ public abstract class Vibrator {
      * to start the repeat, or -1 to disable repeating.
      * 

      *
-     * 
The app should be in foreground for the vibration to happen. Background apps should
+     * 
The app should be in the foreground for the vibration to happen. Background apps should
      * specify a ringtone, notification or alarm usage in order to vibrate.

      *
      * @param pattern    an array of longs of times for which to turn the vibrator on or off.
@@ -428,7 +428,7 @@ public abstract class Vibrator {
     /**
      * Vibrate with a given effect.
      *
-     * 
The app should be in foreground for the vibration to happen.

+     * 
The app should be in the foreground for the vibration to happen.

      *
      * @param vibe {@link VibrationEffect} describing the vibration to be performed.
      */
@@ -440,7 +440,7 @@ public abstract class Vibrator {
     /**
      * Vibrate with a given effect.
      *
-     * 
The app should be in foreground for the vibration to happen. Background apps should
+     * 
The app should be in the foreground for the vibration to happen. Background apps should
      * specify a ringtone, notification or alarm usage in order to vibrate.

      *
      * @param vibe       {@link VibrationEffect} describing the vibration to be performed.
@@ -461,7 +461,7 @@ public abstract class Vibrator {
     /**
      * Vibrate with a given effect.
      *
-     * 
The app should be in foreground for the vibration to happen. Background apps should
+     * 
The app should be in the foreground for the vibration to happen. Background apps should
      * specify a ringtone, notification or alarm usage in order to vibrate.

      *
      * @param vibe       {@link VibrationEffect} describing the vibration to be performed.
@@ -477,7 +477,7 @@ public abstract class Vibrator {
 
     /**
      * Like {@link #vibrate(VibrationEffect, VibrationAttributes)}, but allows the
-     * caller to specify the vibration is owned by someone else and set reason for vibration.
+     * caller to specify the vibration is owned by someone else and set a reason for vibration.
      *
      * @hide
      */
@@ -519,7 +519,7 @@ public abstract class Vibrator {
     }
 
     /**
-     * Query whether the vibrator supports all of the given effects.
+     * Query whether the vibrator supports all the given effects.
      *
      * 
If an effect is not supported, the system may still automatically fall back to a simpler
      * vibration instead, which is not optimised for the specific device, however vibration isn't
@@ -533,7 +533,7 @@ public abstract class Vibrator {
      * vibration.
      *
      * 
If the result is {@link #VIBRATION_EFFECT_SUPPORT_UNKNOWN}, the system doesn't know
-     * whether all of the effects are supported. It may support any or all of the queried effects,
+     * whether all the effects are supported. It may support any or all of the queried effects,
      * but there's no way to programmatically know whether a {@link #vibrate} call will successfully
      * cause a vibration. It's guaranteed, however, that none of the queried effects are
      * definitively unsupported by the hardware.
@@ -541,7 +541,7 @@ public abstract class Vibrator {
      * 
Use {@link #areEffectsSupported(int...)} to get individual results for each effect.
      *
      * @param effectIds Which effects to query for.
-     * @return Whether all of the effects are natively supported by the device.
+     * @return Whether all the effects are natively supported by the device.
      */
     @VibrationEffectSupport
     public final int areAllEffectsSupported(
diff --git a/core/java/android/os/VibratorInfo.java b/core/java/android/os/VibratorInfo.java
index 00ce14fdfd283..71ec0967b3272 100644
--- a/core/java/android/os/VibratorInfo.java
+++ b/core/java/android/os/VibratorInfo.java
@@ -35,7 +35,8 @@ import java.util.Objects;
 /**
  * A VibratorInfo describes the capabilities of a {@link Vibrator}.
  *
- * This description includes its capabilities, list of supported effects and composition primitives.
+ * 
This description includes its capabilities, list of supported effects and composition
+ * primitives.
  *
  * @hide
  */
diff --git a/core/java/android/os/VibratorManager.java b/core/java/android/os/VibratorManager.java
index c82a51669b866..f506ef8955d44 100644
--- a/core/java/android/os/VibratorManager.java
+++ b/core/java/android/os/VibratorManager.java
@@ -25,7 +25,7 @@ import android.content.Context;
 import android.util.Log;
 
 /**
- * Class that provides access to all vibrators from the device, as well as the ability to run them
+ * Provides access to all vibrators from the device, as well as the ability to run them
  * in a synchronized fashion.
  * 

  * If your process exits, any vibration you started will stop.
diff --git a/core/java/android/os/vibrator/VibratorFrequencyProfile.java b/core/java/android/os/vibrator/VibratorFrequencyProfile.java
index 23b45aed8eb4f..0f2aa157d94c1 100644
--- a/core/java/android/os/vibrator/VibratorFrequencyProfile.java
+++ b/core/java/android/os/vibrator/VibratorFrequencyProfile.java
@@ -61,8 +61,7 @@ public final class VibratorFrequencyProfile {
      * 
The returned list will not be empty, and will have entries representing frequencies from
      * {@link #getMinFrequency()} to {@link #getMaxFrequency()}, inclusive.
      *
-     * @return Array of maximum relative amplitude measurements, each value is between 0 and 1,
-     * inclusive.
+     * @return Array of maximum relative amplitude measurements.
      */
     @NonNull
     @FloatRange(from = 0, to = 1)