docs: revise javadocs for sip

add a package description, revise class descriptions and edit some method docs

Change-Id: Ice969a99c830349674c65d99e4b7a6f1d2f24a7e

8 files changed, 118 insertions, 69 deletions

diff --git a/voip/java/android/net/sip/SipAudioCall.java b/voip/java/android/net/sip/SipAudioCall.java
index 6a4014f..b847ff6 100644
--- a/voip/java/android/net/sip/SipAudioCall.java
+++ b/voip/java/android/net/sip/SipAudioCall.java
@@ -37,20 +37,19 @@ import java.util.List;
 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();
@@ -58,7 +57,10 @@ public class SipAudioCall {
     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 class SipAudioCall {
 
     /**
      * 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 class SipAudioCall {
     /**
      * 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 class SipAudioCall {
      * 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 class SipAudioCall {
     /**
      * 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 class SipAudioCall {
      * 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 class SipAudioCall {
 
     /**
      * 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 class SipAudioCall {
     }
 
     /**
-     * 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 class SipAudioCall {
     /**
      * 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
index 6aee5f1..509728f 100644
--- 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
index 225b94f..0339395 100644
--- 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
index 38d2b0c..8aaa805 100644
--- a/voip/java/android/net/sip/SipManager.java
+++ b/voip/java/android/net/sip/SipManager.java
@@ -29,30 +29,29 @@ import android.util.Log;
 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 @@ public class SipManager {
     }
 
     /**
-     * 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 class SipManager {
     }
 
     /**
-     * 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 class SipManager {
     /**
      * 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 class SipManager {
      *        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 class SipManager {
      * 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 class SipManager {
      *        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 class SipManager {
      * 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
index dddb07d..6977e30 100644
--- a/voip/java/android/net/sip/SipProfile.java
+++ b/voip/java/android/net/sip/SipProfile.java
@@ -32,7 +32,10 @@ import javax.sip.address.SipURI;
 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 class SipProfile implements Parcelable, Serializable, Cloneable {
             };
 
     /**
-     * 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
index e1f35ad..9968cc7 100644
--- 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
index 9c08e46..5629b3c 100644
--- a/voip/java/android/net/sip/SipSession.java
+++ b/voip/java/android/net/sip/SipSession.java
@@ -20,14 +20,17 @@ import android.os.RemoteException;
 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 @@ public final class SipSession {
     }
 
     /**
-     * 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
new file mode 100644
index 0000000..790656b
--- /dev/null
+++ b/voip/java/android/net/sip/package.html
@@ -0,0 +1,39 @@
+<HTML>
+<BODY>
+<p>Provides access to Session Initiation Protocol (SIP) functionality, such as
+making and answering VOIP calls using SIP.</p>
+
+<p>To get started, you need to get an instance of the {@link android.net.sip.SipManager} by
+calling {@link android.net.sip.SipManager#newInstance newInstance()}.</p>
+
+<p>With the {@link android.net.sip.SipManager}, you can initiate SIP audio calls with {@link
+android.net.sip.SipManager#makeAudioCall makeAudioCall()} and {@link
+android.net.sip.SipManager#takeAudioCall takeAudioCall()}. Both methods require
+a {@link android.net.sip.SipAudioCall.Listener} that receives callbacks when the state of the
+call changes, such as when the call is ringing, established, or ended.</p>
+
+<p>Both {@link android.net.sip.SipManager#makeAudioCall makeAudioCall()} also requires two
+{@link android.net.sip.SipProfile} objects, representing the local device and the peer
+device. You can create a {@link android.net.sip.SipProfile} using the {@link
+android.net.sip.SipProfile.Builder} subclass.</p>
+
+<p>Once you have a {@link android.net.sip.SipAudioCall}, you can perform SIP audio call actions with
+the instance, such as make a call, answer a call, mute a call, turn on speaker mode, send DTMF
+tones, and more.</p>
+
+<p>If you want to create generic SIP connections (such as for video calls or other), you can
+create a SIP connection from the {@link android.net.sip.SipManager}, using {@link
+android.net.sip.SipManager#open open()}. If you only want to create audio SIP calls, though, you
+should use the {@link android.net.sip.SipAudioCall} class, as described above.</p>
+
+<p class="note"><strong>Note:</strong>
+Not all Android-powered devices support VOIP functionality with SIP. Before performing any SIP
+activity, you should 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 in order to use the SIP APIs.
+</p>
+</BODY>
+</HTML>
\ No newline at end of file