Merge pull request #211 from jeffswartz/misc-docs-edits

Some docs corrections

Author: pardel

src/main/java/com/opentok/OpenTok.java

@@ -300,6 +300,16 @@ public Session createSession() throws OpenTokException {
         return createSession(null);
     }
 
+    /**
+     * Sends a signal to all clients connected to a session.
+     *
+     * <p>
+     * For more information, see the
+     * <a href="https://tokbox.com/developer/guides/signaling/">Signaling developer guide</a>.
+     *
+     * @param sessionId The session ID.
+     * @param props The SignalProperties object that defines the data and type of the signal.
+     */
     public void signal(String sessionId, SignalProperties props) throws OpenTokException , RequestException, InvalidArgumentException {
 
         if (sessionId == null || sessionId.isEmpty() ) {
@@ -315,6 +325,17 @@ public void signal(String sessionId, SignalProperties props) throws OpenTokExcep
 
     }
 
+    /**
+     * Sends a signal to a specific client connected to a session.
+     *
+     * <p>
+     * For more information, see the
+     * <a href="https://tokbox.com/developer/guides/signaling/">Signaling developer guide</a>.
+     *
+     * @param sessionId The session ID.
+     * @param sessionId The connection ID of the client to receive the signal.
+     * @param props The SignalProperties object that defines the data and type of the signal.
+     */
     public void signal(String sessionId, String connectionId, SignalProperties props) throws OpenTokException , RequestException , InvalidArgumentException {
 
         if (sessionId == null || sessionId.isEmpty() || connectionId == null || connectionId.isEmpty()) {
@@ -645,7 +666,7 @@ public void forceDisconnect(String sessionId, String connectionId) throws OpenTo
 
 
     /**
-     * Gets an {@link Stream} object for the given sessionId and streamId.
+     * Gets a {@link Stream} object for the given session ID and stream ID.
      *
      * @param sessionId The session ID.
      * @param streamId The stream ID.
@@ -661,7 +682,7 @@ public Stream getStream(String sessionId, String streamId) throws OpenTokExcepti
     }
 
     /**
-     * Gets a list of {@link Stream} object for the given session ID.
+     * Gets a list of {@link Stream} objects for the given session ID.
      *
      * @param sessionId The session ID.
      *
@@ -679,11 +700,18 @@ public StreamList listStreams(String sessionId) throws OpenTokException {
     }
 
     /**
-     * Gets a list of {@link Stream} object for the given session ID.
+     * Dials a SIP gateway to connect it an OpenTok session.
      *
      * @param sessionId The session ID.
-     * @param token The token.
-     * @param properties The SipProperties.
+     *
+     * @param token  OpenTok token to be used for the participant being called. You can add token
+     * data to identify that the participant is on a SIP endpoint or for other identifying data,
+     * such as phone numbers. (The OpenTok client libraries include properties for inspecting
+     * the connection data for a client connected to a session.) See the
+     * <a href="https://tokbox.com/developer/guides/signaling/">Token Creation developer guide</a>.
+.    *
+     * @param properties The {@link SipProperties} object defining options for the SIP call.
+     *
      * @return The  {@link Sip} object.
      */
     public Sip dial(String sessionId, String token, SipProperties properties) throws OpenTokException {