Docs updates for 4.3.0 API additions (#162)

* Docs updates for 4.3.0 API additions

* Minor docs edit

* README edits

* Fixing a typo.

Author: jeffswartz

README.md

@@ -141,7 +141,7 @@ public String getName() {
     }
 
     /**
-     * The name of the archive.
+     * The resolution of the archive.
      */
     public String getResolution() {
         return resolution;

src/main/java/com/opentok/Archive.java

@@ -11,28 +11,54 @@
 import com.fasterxml.jackson.annotation.JsonValue;
 
 /**
- *  Represents a <a href="https://tokbox.com/developer/guides/archiving/layout-control.html">layout configuration</a>
- *  for a composed archive
+ *  Represents a <a href="https://tokbox.com/developer/guides/archiving/layout-control.html">layout
+ *  configuration</a> for a composed archive.
  */
 @JsonFormat(shape= JsonFormat.Shape.OBJECT)
 public class ArchiveLayout {
     private Type type;
     private String stylesheet;
 
-    public ArchiveLayout(Type type, String stylesheet) {
+    /**
+     * Do not call the <code>ArchiveLayout()</code> constructor. To set the layout of an
+     * archive, call the {@link OpenTok#setArchiveLayout(String archiveId, ArchiveProperties properties)} method.
+     */
+   public ArchiveLayout(Type type, String stylesheet) {
         this.type = type;
         this.stylesheet = stylesheet;
     }
 
+    /**
+     * Do not call the <code>ArchiveLayout()</code> constructor. To set the layout of an
+     * archive, call the {@link OpenTok#setArchiveLayout(String archiveId, ArchiveProperties properties)} method. See 
+     */
     public ArchiveLayout(Type type) {
         this.type = type;
     }
 
+    /**
+     * Enumerates <code>type</code> values for the layout.
+     */
     public enum Type {
+        /**
+         * Represents the picture-in-picture (pip) layout type.
+         */
         PIP("pip"),
+        /**
+         * Represents the picture-in-picture (pip) layout type.
+         */
         BESTFIT("bestFit"),
+        /**
+         * Represents the vertical presentation layout type.
+         */
         VERTICAL("verticalPresentation"),
+        /**
+         * Represents the horizontal presentation layout type.
+         */
         HORIZONTAL("horizontalPresentation"),
+        /**
+         * Represents a custom layout type.
+         */
         CUSTOM("custom");
 
         private String serialized;
@@ -47,18 +73,30 @@ public String toString() {
         }
     }
 
+    /**
+     * Returns the layout type.
+     */
     public Type getType() {
         return type;
     }
 
+    /**
+     * Sets the layout type.
+     */
     public void setType(Type type) {
         this.type = type;
     }
 
+    /**
+     * Returns the stylesheet for a custom layout.
+     */
     public String getStylesheet() {
         return stylesheet;
     }
 
+    /**
+     * Sets the stylesheet for a custom layout.
+     */
     public void setStylesheet(String stylesheet) {
         this.stylesheet = stylesheet;
     }

src/main/java/com/opentok/ArchiveLayout.java

@@ -70,11 +70,12 @@ public Builder name(String name) {
         /**
          * Call this method to set the resolution of the archive.
          *
-         * @param resolution The resolution of the archive, either "640x480" (SD, the default) or "1280x720" (HD).
-         * This property only applies to composed archives.
-         * If you set this property and set the outputMode property to "individual", the call in the API method results in an error.
+         * @param resolution The resolution of the archive, either "640x480" (SD, the default) or
+         * "1280x720" (HD). This property only applies to composed archives. If you set this
+         * and set the outputMode property to "individual", the call in the API method results in
+         * an error.
          *
-         * @return The ArchiveProperties.Builder object with the name setting.
+         * @return The ArchiveProperties.Builder object with the resolution setting.
          */
         public Builder resolution(String resolution) {
             this.resolution = resolution;

src/main/java/com/opentok/ArchiveProperties.java

@@ -17,7 +17,7 @@
 import java.util.Map;
 
 /**
- * Represents an archive of an OpenTok session.
+ * Represents a live streaming broadcast of an OpenTok session.
  */
 @JsonIgnoreProperties(ignoreUnknown=true)
 public class Broadcast {
@@ -32,9 +32,17 @@ public class Broadcast {
     private List<Rtmp> rtmpList = new ArrayList<>();
     private String hls;
 
+    /**
+     * Do not call the <code>Broadcast()</code> constructor. To start a live streaming broadcast,
+     * call the {@link OpenTok#startBroadcast OpenTok.startBroadcast()} method.
+     */
     protected Broadcast() {
     }
 
+    /**
+     * Do not call the <code>makeBroadcast()</code> method. To start a live streaming broadcast,
+     * call the {@link OpenTok#startBroadcast OpenTok.startBroadcast()} method.
+     */
     @JsonCreator
     public static Broadcast makeBroadcast() {
         return new Broadcast();
@@ -48,48 +56,51 @@ public String getId() {
     }
 
     /**
-     * The session ID of the OpenTok session associated with this archive.
+     * The session ID of the OpenTok session associated with this broadcast.
      */
     public String getSessionId() {
         return sessionId;
     }
 
 
     /**
-     * The OpenTok API key associated with the archive.
+     * The OpenTok API key associated with the broadcast.
      */
     public int getProjectId() {
         return projectId;
     }
 
     /**
-     * The time at which the archive was created, in milliseconds since the Unix epoch.
+     * The time at which the broadcast was started, in milliseconds since the Unix epoch.
      */
     public long getCreatedAt() {
         return createdAt;
     }
     /**
-     * The time at which the archive was created, in milliseconds since the Unix epoch.
+     * The time at which the broadcast was updated, in milliseconds since the Unix epoch.
      */
     public long getUpdatedAt() {
         return updatedAt;
     }
     /**
-     * The name of the archive.
+     * The broadcast resolution.
      */
     public String getResolution() {
         return resolution;
     }
 
     /**
-     * The name of the archive.
+     * The broadcast status, either "started" or "stopped".
      */
     public String getStatus() {
         return status;
     }
     /**
-     * The name of the archive.
-     *
+     * Details on the HLS and RTMP broadcast streams. For an HLS stream, the URL is provided.
+     * See the <a href="https://tokbox.com/developer/guides/broadcast/live-streaming/">OpenTok
+     * live streaming broadcast developer guide</a> for more information on how to use this URL.
+     * For each RTMP stream, the RTMP server URL and stream name are provided, along with the RTMP
+     * stream's status.
      */
     @JsonProperty("broadcastUrls")
     private void unpack(Map<String,Object> broadcastUrls) {
@@ -106,13 +117,13 @@ private void unpack(Map<String,Object> broadcastUrls) {
         }
     }
     /**
-     * The name of the archive if present else null.
+     * The HLS URL (if there is one) of the broadcast.
      */
     public String getHls() {
         return hls;
     }
     /**
-     * The name of the archive.
+    * A list of RTMP URLs (if there are any) of the broadcast.
      */
     public List<Rtmp> getRtmpList() {
         return rtmpList;
@@ -124,7 +135,6 @@ public String toString() {
         } catch (Exception e) {
             return "";
         }
-
     }
 
 }

src/main/java/com/opentok/Broadcast.java

@@ -7,11 +7,23 @@
  */
 package com.opentok;
 
+/**
+ *  Represents a <a href="https://tokbox.com/developer/guides/broadcast/live-streaming/#configuring-video-layout-for-opentok-live-streaming-broadcasts">layout
+ *  configuration</a> for a live streaming broadcast.
+ */
 public class BroadcastLayout extends ArchiveLayout {
+    /**
+     * Do not call the <code>BroadcastLayout()</code> constructor. To set the layout of
+     * a live streaming broadcast, call the {@link OpenTok#setBroadcastLayout(String broadcastId, BroadcastProperties properties)} method.
+     */
     public BroadcastLayout(Type type, String stylesheet) {
         super(type, stylesheet);
     }
 
+    /**
+     * Do not call the <code>BroadcastLayout()</code> constructor. To set the layout of
+     * a live streaming broadcast, call the {@link OpenTok#setBroadcastLayout(String broadcastId, BroadcastProperties properties)} method.
+     */
     public BroadcastLayout(Type type) {
         super(type);
     }

src/main/java/com/opentok/BroadcastLayout.java

@@ -15,9 +15,7 @@
 
 /**
  * Defines values for the <code>properties</code> parameter of the
- * {@link OpenTok#createSession(SessionProperties)} method.
- *
- * @see OpenTok#createSession(com.opentok.SessionProperties properties)
+ * {@link OpenTok#startBroadcast(String sessionId, BroadcastProperties properties)} method.
  */
 public class BroadcastProperties {
 
@@ -50,9 +48,9 @@ public static class Builder {
 
 
         /**
-         * Call this method to customize the layout of the broadcast
+         * Call this method to customize the layout of the broadcast.
          *
-         * @param layout An object of type {@link BroadcastLayout} .
+         * @param layout An object of type {@link BroadcastLayout}.
          *
          * @return The BroadcastProperties.Builder object with the layout setting.
          */
@@ -61,9 +59,12 @@ public Builder layout(BroadcastLayout layout){
             return this;
         }
         /**
-         * Call this method to set the time duration, in seconds, of the broadcast . The default is 7200 seconds
+         * Call this method to set the maximum duration, in seconds, of the broadcast.
+         * The broadcast will automatically stop when the maximum duration is reached.
+         * You can set the maximum duration to a value from 60 (60 seconds) to 36000 (10 hours).
+         * The default maximum duration is 2 hours (7200 seconds).
          *
-         * @param maxDuration The maximum time duration in seconds
+         * @param maxDuration The maximum duration in seconds.
          *
          * @return The BroadcastProperties.Builder object with the maxDuration setting.
          */
@@ -87,9 +88,10 @@ public Builder hasHls(boolean hasHls) {
             return this;
         }
         /**
-         * Call this method to set rtmp list of the broadcast stream. A limit of 5 RtmpProperties object is enforced.
+         * Call this method to set a list of RTMP broadcast streams. There is a limit of
+         * 5 RTMP streams.
          *
-         * @param rtmpProps The rtmp properties object .
+         * @param rtmpProps The {@link RtmpProperties} object defining the RTMP streams.
          *
          * @return The BroadcastProperties.Builder object with the list of RtmpProperties setting.
          */

src/main/java/com/opentok/BroadcastProperties.java

@@ -497,14 +497,7 @@ public void deleteArchive(String archiveId) throws OpenTokException {
      *
      * @param archiveId {String} The archive ID.
      *
-     * @param properties This ArchiveProperties object defines options for the archive.
-     *
-     * The ArchiveProperties values has the following constraints:
-     * Valid layout type values are "bestFit" (best fit), "custom" (custom), "horizontalPresentation" (horizontal presentation),
-     * "pip" (picture-in-picture), and "verticalPresentation" (vertical presentation)).
-     *  If you specify a "custom" layout type, set the stylesheet property to the stylesheet.
-     *  (For other layout types, do not set the stylesheet property.)
-     *  Refer https://tokbox.com/developer/rest/#change_composed_archive_layout for more details
+     * @param properties This ArchiveProperties object defining the arachive layout.
      */
     public void setArchiveLayout(String archiveId, ArchiveProperties properties) throws OpenTokException {
         if (StringUtils.isEmpty(archiveId) || properties == null) {
@@ -528,11 +521,12 @@ public void setArchiveLayout(String archiveId, ArchiveProperties properties) thr
      * For more information on broadcasting, see the
      * <a href="https://tokbox.com/developer/guides/broadcast/">Broadcast developer guide.</a>
      *
-     * @param sessionId The session ID of the broadcasting session
+     * @param sessionId The session ID of the OpenTok session to broadcast.
      *
      * @param properties This BroadcastProperties object defines options for the broadcast.
      *
-     * @return The Broadcast object. This object includes properties defining the archive, including the archive ID.
+     * @return The Broadcast object. This object includes properties defining the broadcast,
+     * including the broadcast ID.
      */
     public Broadcast startBroadcast(String sessionId, BroadcastProperties properties) throws OpenTokException {
         if (StringUtils.isEmpty(sessionId) || (properties ==  null)) {
@@ -590,19 +584,13 @@ public Broadcast getBroadcast(String broadcastId) throws OpenTokException {
     }
     /**
      * Sets the layout type for the broadcast. For a description of layout types, see
-     *  <a href="https://tokbox.com/developer/guides/archiving/layout-control.html">Customizing
-     *  the video layout for composed archives</a>.
+     * <a href="hhttps://tokbox.com/developer/guides/broadcast/live-streaming/#configuring-video-layout-for-opentok-live-streaming-broadcasts">Configuring
+     * video layout for OpenTok live streaming broadcasts</a>.
      *
      * @param broadcastId {String} The broadcast ID.
      *
-     * @param properties This BroadcastProperties object defines options for the archive.
-     *
-     * The ArchiveProperties values has the following constraints:
-     * Valid layout type values are "bestFit" (best fit), "custom" (custom), "horizontalPresentation" (horizontal presentation),
-     * "pip" (picture-in-picture), and "verticalPresentation" (vertical presentation)).
-     *  If you specify a "custom" layout type, set the stylesheet property to the stylesheet.
-     *  (For other layout types, do not set the stylesheet property.)
-     *  Refer https://tokbox.com/developer/rest/#change_composed_archive_layout for more details
+     * @param properties This BroadcastProperties object that defines layout options for
+     * the broadcast.
      */
     public void setBroadcastLayout(String broadcastId, BroadcastProperties properties) throws OpenTokException {
         if (StringUtils.isEmpty(broadcastId) || properties == null) {

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

@@ -10,7 +10,7 @@
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 
 /**
- * Represents a stream in an OpenTok session.
+ * Represents an RTMP stream in an OpenTok session.
  */
 @JsonIgnoreProperties(ignoreUnknown=true)
 
@@ -29,7 +29,7 @@ public String getId() {
         return id;
     }
     /**
-     * The server URL.
+     * The RTMP server URL.
      */
     public void setServerUrl(String serverUrl) {
         this.serverUrl = serverUrl;
@@ -46,7 +46,5 @@ public void setStreamName(String streamName) {
     public String getStreamName() {
         return streamName;
     }
-
-
 }