Merge "docs: revise javadocs for sip add a package description, revise class descriptions and edit some method docs" into gingerbread

scottamain · Android (Google) Code Review · commit 1112632a4146 · 2010-10-29T10:03:36.000-07:00
diff --git a/voip/java/android/net/sip/SipAudioCall.java b/voip/java/android/net/sip/SipAudioCall.java
@@ -37,28 +37,30 @@
 import java.util.Map;
 
 /**
- * Class that handles an Internet audio call over SIP. {@link SipManager}
- * facilitates instantiating a {@code SipAudioCall} object for making/receiving
- * calls. See {@link SipManager#makeAudioCall} and
- * {@link SipManager#takeAudioCall}.
+ * Handles an Internet audio call over SIP. You can instantiate this class with {@link SipManager},
+ * using {@link SipManager#makeAudioCall makeAudioCall()} and  {@link SipManager#takeAudioCall
+ * takeAudioCall()}.
  *
- * <p>Requires permissions to use this class:
+ * <p class="note"><strong>Note:</strong> Using this class require the
  *   {@link android.Manifest.permission#INTERNET} and
- *   {@link android.Manifest.permission#USE_SIP}.
- * <br/>Requires permissions to {@link #startAudio}:
+ *   {@link android.Manifest.permission#USE_SIP} permissions.<br/><br/>In addition, {@link
+ *   #startAudio} requires the
  *   {@link android.Manifest.permission#RECORD_AUDIO},
- *   {@link android.Manifest.permission#ACCESS_WIFI_STATE} and
- *   {@link android.Manifest.permission#WAKE_LOCK}.
- * <br/>Requires permissions to {@link #setSpeakerMode}:
- *   {@link android.Manifest.permission#MODIFY_AUDIO_SETTINGS}.
+ *   {@link android.Manifest.permission#ACCESS_WIFI_STATE}, and
+ *   {@link android.Manifest.permission#WAKE_LOCK} permissions; and {@link #setSpeakerMode
+ *   setSpeakerMode()} requires the
+ *   {@link android.Manifest.permission#MODIFY_AUDIO_SETTINGS} permission.</p>
  */
 public class SipAudioCall {
     private static final String TAG = SipAudioCall.class.getSimpleName();
     private static final boolean RELEASE_SOCKET = true;
     private static final boolean DONT_RELEASE_SOCKET = false;
     private static final int SESSION_TIMEOUT = 5; // in seconds
 
-    /** Listener class for all event callbacks. */
+    /** Listener for events relating to a SIP call, such as when a call is being
+     * recieved ("on ringing") or a call is outgoing ("on calling").
+     * <p>Many of these events are also received by {@link SipSession.Listener}.</p>
+     */
     public static class Listener {
         /**
          * Called when the call object is ready to make another call.
@@ -199,7 +201,7 @@ public SipAudioCall(Context context, SipProfile localProfile) {
 
     /**
      * Sets the listener to listen to the audio call events. The method calls
-     * {@code setListener(listener, false)}.
+     * {@link #setListener setListener(listener, false)}.
      *
      * @param listener to listen to the audio call events of this object
      * @see #setListener(Listener, boolean)
@@ -537,14 +539,14 @@ public void attachCall(SipSession session, String sessionDescription)
     /**
      * Initiates an audio call to the specified profile. The attempt will be
      * timed out if the call is not established within {@code timeout} seconds
-     * and {@code Listener.onError(SipAudioCall, SipErrorCode.TIME_OUT, String)}
+     * and {@link Listener#onError onError(SipAudioCall, SipErrorCode.TIME_OUT, String)}
      * will be called.
      *
      * @param peerProfile the SIP profile to make the call to
      * @param sipSession the {@link SipSession} for carrying out the call
      * @param timeout the timeout value in seconds. Default value (defined by
      *        SIP protocol) is used if {@code timeout} is zero or negative.
-     * @see Listener.onError
+     * @see Listener#onError
      * @throws SipException if the SIP service fails to create a session for the
      *        call
      */
@@ -582,12 +584,12 @@ public void endCall() throws SipException {
      * Puts a call on hold.  When succeeds, {@link Listener#onCallHeld} is
      * called. The attempt will be timed out if the call is not established
      * within {@code timeout} seconds and
-     * {@code Listener.onError(SipAudioCall, SipErrorCode.TIME_OUT, String)}
+     * {@link Listener#onError onError(SipAudioCall, SipErrorCode.TIME_OUT, String)}
      * will be called.
      *
      * @param timeout the timeout value in seconds. Default value (defined by
      *        SIP protocol) is used if {@code timeout} is zero or negative.
-     * @see Listener.onError
+     * @see Listener#onError
      * @throws SipException if the SIP service fails to hold the call
      */
     public void holdCall(int timeout) throws SipException {
@@ -604,12 +606,12 @@ public void holdCall(int timeout) throws SipException {
     /**
      * Answers a call. The attempt will be timed out if the call is not
      * established within {@code timeout} seconds and
-     * {@code Listener.onError(SipAudioCall, SipErrorCode.TIME_OUT, String)}
+     * {@link Listener#onError onError(SipAudioCall, SipErrorCode.TIME_OUT, String)}
      * will be called.
      *
      * @param timeout the timeout value in seconds. Default value (defined by
      *        SIP protocol) is used if {@code timeout} is zero or negative.
-     * @see Listener.onError
+     * @see Listener#onError
      * @throws SipException if the SIP service fails to answer the call
      */
     public void answerCall(int timeout) throws SipException {
@@ -628,12 +630,12 @@ public void answerCall(int timeout) throws SipException {
      * Continues a call that's on hold. When succeeds,
      * {@link Listener#onCallEstablished} is called. The attempt will be timed
      * out if the call is not established within {@code timeout} seconds and
-     * {@code Listener.onError(SipAudioCall, SipErrorCode.TIME_OUT, String)}
+     * {@link Listener#onError onError(SipAudioCall, SipErrorCode.TIME_OUT, String)}
      * will be called.
      *
      * @param timeout the timeout value in seconds. Default value (defined by
      *        SIP protocol) is used if {@code timeout} is zero or negative.
-     * @see Listener.onError
+     * @see Listener#onError
      * @throws SipException if the SIP service fails to unhold the call
      */
     public void continueCall(int timeout) throws SipException {
@@ -786,8 +788,8 @@ public boolean isMuted() {
 
     /**
      * Puts the device to speaker mode.
-     * <p>Requires permission:
-     *   {@link android.Manifest.permission#MODIFY_AUDIO_SETTINGS}.
+     * <p class="note"><strong>Note:</strong> Requires the
+     *   {@link android.Manifest.permission#MODIFY_AUDIO_SETTINGS} permission.</p>
      */
     public void setSpeakerMode(boolean speakerMode) {
         synchronized (this) {
@@ -797,20 +799,21 @@ public void setSpeakerMode(boolean speakerMode) {
     }
 
     /**
-     * Sends a DTMF code. According to RFC2833, event 0--9 maps to decimal
+     * Sends a DTMF code. According to <a href="http://tools.ietf.org/html/rfc2833">RFC 2883</a>,
+     * event 0--9 maps to decimal
      * value 0--9, '*' to 10, '#' to 11, event 'A'--'D' to 12--15, and event
      * flash to 16. Currently, event flash is not supported.
      *
      * @param code the DTMF code to send. Value 0 to 15 (inclusive) are valid
      *        inputs.
-     * @see http://tools.ietf.org/html/rfc2833
      */
     public void sendDtmf(int code) {
         sendDtmf(code, null);
     }
 
     /**
-     * Sends a DTMF code. According to RFC2833, event 0--9 maps to decimal
+     * Sends a DTMF code. According to <a href="http://tools.ietf.org/html/rfc2833">RFC 2883</a>,
+     * event 0--9 maps to decimal
      * value 0--9, '*' to 10, '#' to 11, event 'A'--'D' to 12--15, and event
      * flash to 16. Currently, event flash is not supported.
      *
@@ -888,10 +891,10 @@ public void setAudioGroup(AudioGroup group) {
     /**
      * Starts the audio for the established call. This method should be called
      * after {@link Listener#onCallEstablished} is called.
-     * <p>Requires permission:
+     * <p class="note"><strong>Note:</strong> Requires the
      *   {@link android.Manifest.permission#RECORD_AUDIO},
      *   {@link android.Manifest.permission#ACCESS_WIFI_STATE} and
-     *   {@link android.Manifest.permission#WAKE_LOCK}.
+     *   {@link android.Manifest.permission#WAKE_LOCK} permissions.</p>
      */
     public void startAudio() {
         try {
diff --git a/voip/java/android/net/sip/SipErrorCode.java b/voip/java/android/net/sip/SipErrorCode.java
@@ -17,11 +17,11 @@
 package android.net.sip;
 
 /**
- * Defines error code returned in
- * {@link SipRegistrationListener#onRegistrationFailed},
- * {@link SipSession.Listener#onError},
- * {@link SipSession.Listener#onCallChangeFailed} and
- * {@link SipSession.Listener#onRegistrationFailed}.
+ * Defines error codes returned during SIP actions. For example, during
+ * {@link SipRegistrationListener#onRegistrationFailed onRegistrationFailed()},
+ * {@link SipSession.Listener#onError onError()},
+ * {@link SipSession.Listener#onCallChangeFailed onCallChangeFailed()} and
+ * {@link SipSession.Listener#onRegistrationFailed onRegistrationFailed()}.
  */
 public class SipErrorCode {
     /** Not an error. */
diff --git a/voip/java/android/net/sip/SipException.java b/voip/java/android/net/sip/SipException.java
@@ -17,7 +17,7 @@
 package android.net.sip;
 
 /**
- * General SIP-related exception class.
+ * Indicates a general SIP-related exception.
  */
 public class SipException extends Exception {
     public SipException() {
diff --git a/voip/java/android/net/sip/SipManager.java b/voip/java/android/net/sip/SipManager.java
@@ -29,30 +29,29 @@
 import java.text.ParseException;
 
 /**
- * The class provides API for various SIP related tasks. Specifically, the API
- * allows an application to:
+ * Provides APIs for SIP tasks, such as initiating SIP connections, and provides access to related
+ * SIP services. This class is the starting point for any SIP actions. You can acquire an instance
+ * of it with {@link #newInstance newInstance()}.</p>
+ * <p>The APIs in this class allows you to:</p>
  * <ul>
- * <li>open a {@link SipProfile} to get ready for making outbound calls or have
- *      the background SIP service listen to incoming calls and broadcast them
- *      with registered command string. See
- *      {@link #open(SipProfile, PendingIntent, SipRegistrationListener)},
- *      {@link #open(SipProfile)}, {@link #close}, {@link #isOpened} and
- *      {@link #isRegistered}. It also facilitates handling of the incoming call
- *      broadcast intent. See
- *      {@link #isIncomingCallIntent}, {@link #getCallId},
- *      {@link #getOfferSessionDescription} and {@link #takeAudioCall}.</li>
- * <li>make/take SIP-based audio calls. See
- *      {@link #makeAudioCall} and {@link #takeAudioCall}.</li>
- * <li>register/unregister with a SIP service provider manually. See
- *      {@link #register} and {@link #unregister}.</li>
- * <li>process SIP events directly with a {@link SipSession} created by
- *      {@link #createSipSession}.</li>
+ * <li>Create a {@link SipSession} to get ready for making calls or listen for incoming calls. See
+ * {@link #createSipSession createSipSession()} and {@link #getSessionFor getSessionFor()}.</li>
+ * <li>Initiate and receive generic SIP calls or audio-only SIP calls. Generic SIP calls may
+ * be video, audio, or other, and are initiated with {@link #open open()}. Audio-only SIP calls
+ * should be handled with a {@link SipAudioCall}, which you can acquire with {@link
+ * #makeAudioCall makeAudioCall()} and {@link #takeAudioCall takeAudioCall()}.</li>
+ * <li>Register and unregister with a SIP service provider, with
+ *      {@link #register register()} and {@link #unregister unregister()}.</li>
+ * <li>Verify session connectivity, with {@link #isOpened isOpened()} and
+ *      {@link #isRegistered isRegistered()}.</li>
  * </ul>
- * {@code SipManager} can only be instantiated if SIP API is supported by the
- * device. (See {@link #isApiSupported}).
- * <p>Requires permissions to use this class:
- *   {@link android.Manifest.permission#INTERNET} and
- *   {@link android.Manifest.permission#USE_SIP}.
+ * <p class="note"><strong>Note:</strong> Not all Android-powered devices support VOIP calls using
+ * SIP. You should always call {@link android.net.sip.SipManager#isVoipSupported
+ * isVoipSupported()} to verify that the device supports VOIP calling and {@link
+ * android.net.sip.SipManager#isApiSupported isApiSupported()} to verify that the device supports
+ * the SIP APIs.<br/><br/>Your application must also request the {@link
+ * android.Manifest.permission#INTERNET} and {@link android.Manifest.permission#USE_SIP}
+ * permissions.</p>
  */
 public class SipManager {
     /**
@@ -160,7 +159,7 @@ private void createSipService() {
     }
 
     /**
-     * Opens the profile for making calls. The caller may make subsequent calls
+     * Opens the profile for making generic SIP calls. The caller may make subsequent calls
      * through {@link #makeAudioCall}. If one also wants to receive calls on the
      * profile, use
      * {@link #open(SipProfile, PendingIntent, SipRegistrationListener)}
@@ -179,7 +178,7 @@ public void open(SipProfile localProfile) throws SipException {
     }
 
     /**
-     * Opens the profile for making calls and/or receiving calls. The caller may
+     * Opens the profile for making calls and/or receiving generic SIP calls. The caller may
      * make subsequent calls through {@link #makeAudioCall}. If the
      * auto-registration option is enabled in the profile, the SIP service
      * will register the profile to the corresponding SIP provider periodically
@@ -296,7 +295,7 @@ public boolean isRegistered(String localProfileUri) throws SipException {
     /**
      * Creates a {@link SipAudioCall} to make a call. The attempt will be timed
      * out if the call is not established within {@code timeout} seconds and
-     * {@code SipAudioCall.Listener.onError(SipAudioCall, SipErrorCode.TIME_OUT, String)}
+     * {@link SipAudioCall.Listener#onError onError(SipAudioCall, SipErrorCode.TIME_OUT, String)}
      * will be called.
      *
      * @param localProfile the SIP profile to make the call from
@@ -307,7 +306,7 @@ public boolean isRegistered(String localProfileUri) throws SipException {
      *        SIP protocol) is used if {@code timeout} is zero or negative.
      * @return a {@link SipAudioCall} object
      * @throws SipException if calling the SIP service results in an error
-     * @see SipAudioCall.Listener.onError
+     * @see SipAudioCall.Listener#onError
      */
     public SipAudioCall makeAudioCall(SipProfile localProfile,
             SipProfile peerProfile, SipAudioCall.Listener listener, int timeout)
@@ -327,7 +326,7 @@ public SipAudioCall makeAudioCall(SipProfile localProfile,
      * Creates a {@link SipAudioCall} to make an audio call. The attempt will be
      * timed out if the call is not established within {@code timeout} seconds
      * and
-     * {@code SipAudioCall.Listener.onError(SipAudioCall, SipErrorCode.TIME_OUT, String)}
+     * {@link SipAudioCall.Listener#onError onError(SipAudioCall, SipErrorCode.TIME_OUT, String)}
      * will be called.
      *
      * @param localProfileUri URI of the SIP profile to make the call from
@@ -338,7 +337,7 @@ public SipAudioCall makeAudioCall(SipProfile localProfile,
      *        SIP protocol) is used if {@code timeout} is zero or negative.
      * @return a {@link SipAudioCall} object
      * @throws SipException if calling the SIP service results in an error
-     * @see SipAudioCall.Listener.onError
+     * @see SipAudioCall.Listener#onError
      */
     public SipAudioCall makeAudioCall(String localProfileUri,
             String peerProfileUri, SipAudioCall.Listener listener, int timeout)
@@ -449,7 +448,7 @@ public static Intent createIncomingCallBroadcast(String callId,
      * receiving calls.
      * {@link #open(SipProfile, PendingIntent, SipRegistrationListener)} is
      * still needed to be called at least once in order for the SIP service to
-     * notify the caller with the {@code PendingIntent} when an incoming call is
+     * notify the caller with the {@link android.app.PendingIntent} when an incoming call is
      * received.
      *
      * @param localProfile the SIP profile to register with
diff --git a/voip/java/android/net/sip/SipProfile.java b/voip/java/android/net/sip/SipProfile.java
@@ -32,7 +32,10 @@
 import javax.sip.address.URI;
 
 /**
- * Class containing a SIP account, domain and server information.
+ * Defines a SIP profile, including a SIP account, domain and server information.
+ * <p>You can create a {@link SipProfile} using {@link
+ * SipProfile.Builder}. You can also retrieve one from a {@link SipSession}, using {@link
+ * SipSession#getLocalProfile} and {@link SipSession#getPeerProfile}.</p>
  */
 public class SipProfile implements Parcelable, Serializable, Cloneable {
     private static final long serialVersionUID = 1L;
@@ -59,7 +62,7 @@ public SipProfile[] newArray(int size) {
             };
 
     /**
-     * Class to help create a {@code SipProfile}.
+     * Helper class for creating a {@link SipProfile}.
      */
     public static class Builder {
         private AddressFactory mAddressFactory;
diff --git a/voip/java/android/net/sip/SipRegistrationListener.java b/voip/java/android/net/sip/SipRegistrationListener.java
@@ -17,7 +17,7 @@
 package android.net.sip;
 
 /**
- * Listener class to listen to SIP registration events.
+ * Listener for SIP registration events.
  */
 public interface SipRegistrationListener {
     /**
diff --git a/voip/java/android/net/sip/SipSession.java b/voip/java/android/net/sip/SipSession.java
@@ -20,14 +20,17 @@
 import android.util.Log;
 
 /**
- * A SIP session that is associated with a SIP dialog or a standalone
+ * Represents a SIP session that is associated with a SIP dialog or a standalone
  * transaction not within a dialog.
+ * <p>You can get a {@link SipSession} from {@link SipManager} with {@link
+ * SipManager#createSipSession createSipSession()} (when initiating calls) or {@link
+ * SipManager#getSessionFor getSessionFor()} (when receiving calls).</p>
  */
 public final class SipSession {
     private static final String TAG = "SipSession";
 
     /**
-     * Defines {@link SipSession} states.
+     * Defines SIP session states, such as "registering", "outgoing call", and "in call".
      */
     public static class State {
         /** When session is ready to initiate a call or transaction. */
@@ -98,7 +101,9 @@ private State() {
     }
 
     /**
-     * Listener class that listens to {@link SipSession} events.
+     * Listener for events relating to a SIP session, such as when a session is being registered
+     * ("on registering") or a call is outgoing ("on calling").
+     * <p>Many of these events are also received by {@link SipAudioCall.Listener}.</p>
      */
     public static class Listener {
         /**
diff --git a/voip/java/android/net/sip/package.html b/voip/java/android/net/sip/package.html
