Merge "Removed reference to developer guide from class description. Added some missing parameter and return descriptions."

media/java/android/media/JetPlayer.java

@@ -31,35 +31,33 @@ import java.lang.ref.WeakReference;
 
 /**
  * JetPlayer provides access to JET content playback and control.
- * 
+ *
- * <p>Please refer to the JET Creator User Manual for a presentation of the JET interactive
+ * <p>Please refer to the
- * music concept and how to use the JetCreator tool to create content to be player by JetPlayer.
+ * <a href="https://developer.android.com/guide/topics/media/jet/jetcreator_manual">JET Creator User
- * 
+ * Manual</a> for a presentation of the JET interactive music concept and how to use the JetCreator
+ * tool to create content to be player by JetPlayer.
+ *
  * <p>Use of the JetPlayer class is based around the playback of a number of JET segments
  * sequentially added to a playback FIFO queue. The rendering of the MIDI content stored in each
  * segment can be dynamically affected by two mechanisms:
  * <ul>
- * <li>tracks in a segment can be muted or unmuted at any moment, individually or through
+ *   <li>Tracks in a segment can be muted or unmuted at any moment, individually or through a mask
- *    a mask (to change the mute state of multiple tracks at once)</li>
+ *       (to change the mute state of multiple tracks at once).
- * <li>parts of tracks in a segment can be played at predefined points in the segment, in order
+ *   <li>Parts of tracks in a segment can be played at predefined points in the segment, in order to
- *    to maintain synchronization with the other tracks in the segment. This is achieved through
+ *       maintain synchronization with the other tracks in the segment. This is achieved through the
- *    the notion of "clips", which can be triggered at any time, but that will play only at the
+ *       notion of "clips", which can be triggered at any time, but that will play only at the right
- *    right time, as authored in the corresponding JET file.</li>
+ *       time, as authored in the corresponding JET file.
  * </ul>
- * As a result of the rendering and playback of the JET segments, the user of the JetPlayer instance
- * can receive notifications from the JET engine relative to:
- * <ul>
- * <li>the playback state,</li>
- * <li>the number of segments left to play in the queue,</li>
- * <li>application controller events (CC80-83) to mark points in the MIDI segments.</li>
- * </ul>
- * Use {@link #getJetPlayer()} to construct a JetPlayer instance. JetPlayer is a singleton class.
- * </p>
  *
- * <div class="special reference">
+ * <p>As a result of the rendering and playback of the JET segments, the user of the JetPlayer
- * <h3>Developer Guides</h3>
+ * instance can receive notifications from the JET engine relative to:
- * <p>For more information about how to use JetPlayer, read the
+ * <ul>
- * <a href="{@docRoot}guide/topics/media/jetplayer.html">JetPlayer</a> developer guide.</p></div>
+ *   <li>Playback state
+ *   <li>Number of segments left to play in the queue
+ *   <li>Application controller events (CC80-83) to mark points in the MIDI segments
+ * </ul>
+ *
+ * <p>Use {@link #getJetPlayer()} to construct a JetPlayer instance. JetPlayer is a singleton class.
  */
 public class JetPlayer
 {    
@@ -140,7 +138,7 @@ public class JetPlayer
     //------------------------
     /**
      * Factory method for the JetPlayer class.
-     * @return the singleton JetPlayer instance
+     * @return the singleton JetPlayer instance.
      */
     public static JetPlayer getJetPlayer() {
         if (singletonRef == null) {
@@ -203,7 +201,8 @@ public class JetPlayer
     // Getters
     //------------------------
     /**
-     * Returns the maximum number of simultaneous MIDI tracks supported by JetPlayer
+     * Gets the maximum number of simultaneous MIDI tracks supported by JetPlayer.
+     * @return the maximum number of simultaneous MIDI tracks supported by JetPlayer.
      */
     public static int getMaxTracks() {
         return JetPlayer.MAXTRACKS;
@@ -459,10 +458,9 @@ public class JetPlayer
     //------------------------
     /**
      * Sets the listener JetPlayer notifies when a JET event is generated by the rendering and
-     * playback engine.
+     * playback engine. Notifications are received in the same thread as the one in which the
-     * Notifications will be received in the same thread as the one in which the JetPlayer
+     * JetPlayer instance was created.
-     * instance was created.
+     * @param listener the listener that will be notified when a JET event is generated.
-     * @param listener
      */
     public void setEventListener(OnJetEventListener listener) {
         setEventListener(listener, null);
@@ -470,10 +468,9 @@ public class JetPlayer
     
     /**
      * Sets the listener JetPlayer notifies when a JET event is generated by the rendering and
-     * playback engine.
+     * playback engine. Use this method to receive JET events in the Handler associated with
-     * Use this method to receive JET events in the Handler associated with another
+     * another thread than the one in which you created the JetPlayer instance.
-     * thread than the one in which you created the JetPlayer instance.
+     * @param listener the listener that will be notified when a JET event is generated.
-     * @param listener
      * @param handler the Handler that will receive the event notification messages.
      */
     public void setEventListener(OnJetEventListener listener, Handler handler) {