Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 447f56e5 authored by Simon Bowden's avatar Simon Bowden
Browse files

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 <pre> 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
parent 53745829

core/java/android/os/VibrationAttributes.java

+2 −2
Original line number Diff line number Diff line
@@ -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();

    }

core/java/android/os/VibrationEffect.java

+46 −51
Original line number Diff line number Diff line
@@ -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.

 * <p>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

     * <p>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

     * <p>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

     * <p>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

     * <p>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

     * <p>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

     * <p>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

     * <p>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.

     * <p>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

     * <p>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

     * <p>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:

     *

     * <code>

     * VibrationEffect effect = VibrationEffect.startComposition()

     * <pre>

     * {@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();

     * </code>

     *     .compose();}</pre>

     *

     * <p>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:

     *

     * <code>

     * VibrationEffect repeatingEffect = VibrationEffect.startComposition()

     * <pre>

     * {@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();

     * </code>

     *     .compose();}</pre>

     *

     * <p>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

         * <p>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.

         * <p>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.

         * <p>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 { 
     * <p>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:

     *

     * <code>

     * import static android.os.VibrationEffect.VibrationParameter.targetAmplitude;

     * <pre>

     * {@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();

     * </code>

     *     .build();}</pre>

     *

     * <p>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.

     *

     * <code>

     * VibrationEffect patternToBeRepeated = VibrationEffect.startWaveform(targetAmplitude(0.2f))

     * <pre>

     * {@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();

     * </code>

     *     .repeatEffectIndefinitely(patternToRepeat)

     *     .compose();}</pre>

     *

     * <p>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:

     *

     * <code>

     * // These two effects are the same

     * <pre>

     * {@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();

     * </code>

     *     .build();}</pre>

     *

     * @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

         * <p>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.

         *

core/java/android/os/Vibrator.java

+14 −14
Original line number Diff line number Diff line
@@ -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

     * <p>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.

     * <p>This effect is supported by the underlying hardware.

     */

    public static final int VIBRATION_EFFECT_SUPPORT_YES = 1;



    /**

     * Vibration effect support: unsupported

     *

     * This effect is <b>not</b> natively supported by the underlying hardware, although

     * <p>This effect is <b>not</b> 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.

     *

     * <p>The app should be in foreground for the vibration to happen.</p>

     * <p>The app should be in the foreground for the vibration to happen.</p>

     *

     * @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.

     *

     * <p>The app should be in foreground for the vibration to happen. Background apps should

     * <p>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.</p>

     *

     * @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.

     * </p>

     *

     * <p>The app should be in foreground for the vibration to happen.</p>

     * <p>The app should be in the 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
@@ -395,7 +395,7 @@ 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

     * <p>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.</p>

     *

     * @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.

     *

     * <p>The app should be in foreground for the vibration to happen.</p>

     * <p>The app should be in the foreground for the vibration to happen.</p>

     *

     * @param vibe {@link VibrationEffect} describing the vibration to be performed.

     */
@@ -440,7 +440,7 @@ public abstract class Vibrator { 
    /**

     * Vibrate with a given effect.

     *

     * <p>The app should be in foreground for the vibration to happen. Background apps should

     * <p>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.</p>

     *

     * @param vibe       {@link VibrationEffect} describing the vibration to be performed.
@@ -461,7 +461,7 @@ public abstract class Vibrator { 
    /**

     * Vibrate with a given effect.

     *

     * <p>The app should be in foreground for the vibration to happen. Background apps should

     * <p>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.</p>

     *

     * @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.

     *

     * <p>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.

     *

     * <p>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 { 
     * <p>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(

core/java/android/os/VibratorInfo.java

+2 −1
Original line number Diff line number Diff line
@@ -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.

 * <p>This description includes its capabilities, list of supported effects and composition

 * primitives.

 *

 * @hide

 */

core/java/android/os/VibratorManager.java

+1 −1
Original line number Diff line number Diff line
@@ -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.

 * <p>

 * If your process exits, any vibration you started will stop.