Merge pull request #295 from jeffswartz/fix-phpdoc

Fix phpdoc

Author: SecondeJK

.gitignore

@@ -7,3 +7,8 @@ phpunit.xml
 sample/*/vendor/
 sample/*/cache/
 composer.lock
+
+docs/
+.phpdoc/
+phpDocumentor*
+.phpunit.result.cache

DEVELOPING.md

@@ -20,6 +20,13 @@ This project's tests are written as PHPUnit test cases. Common tasks:
 
 *  `./vendor/bin/phing test` - run the test suite.
 
+### Building docs
+
+Install [PhpDocumentor](https://docs.phpdoc.org/). Add it to the project root directory.
+Then run `php phpDocumentor.phar --config phpdoc.dist.xml`.
+
+The current reference docs were built with PhpDocumentor 3.3.0.
+
 ### Releasing
 
 In order to create a release, the following should be completed in order.

README.md

@@ -427,7 +427,7 @@ $opentok->signal($sessionId, $signalPayload);
 For more information, see the [OpenTok signaling developer
 guide](https://tokbox.com/developer/guides/signaling/).
 
-## Working with SIP Interconnect
+### Working with SIP Interconnect
 
 You can add an audio-only stream from an external third-party SIP gateway using the SIP
 Interconnect feature. This requires a SIP URI, the session ID you wish to add the audio-only
@@ -457,59 +457,6 @@ $opentok->dial($sessionId, $token, $sipUri, $options);
 For more information, see the [OpenTok SIP Interconnect developer
 guide](https://tokbox.com/developer/guides/sip/).
 
-## Force Disconnect
-
-Your application server can disconnect a client from an OpenTok session by calling the `forceDisconnect($sessionId, $connectionId)`
-method of the `OpenTok\OpenTok` class.
-
-```php
-use OpenTok\OpenTok;
-
-// Force disconnect a client connection
-$opentok->forceDisconnect($sessionId, $connectionId);
-```
-
-## Sending Signals
-
-Once a Session is created, you can send signals to everyone in the session or to a specific connection.
-You can send a signal by calling the `signal($sessionId, $payload, $connectionId)` method of the
-`OpenTok\OpenTok` class.
-
-The `$sessionId` parameter is the session ID of the session.
-
-The `$payload` parameter is an associative array used to set the
-following:
-
-- `data` (string) -- The data string for the signal. You can send a maximum of 8kB.
-
-- `type` (string) -- — (Optional) The type string for the signal. You can send a maximum of 128 characters, and only the following characters are allowed: A-Z, a-z, numbers (0-9), '-', '\_', and '~'.
-
-The `$connectionId` parameter is an optional string used to specify the connection ID of
-a client connected to the session. If you specify this value, the signal is sent to
-the specified client. Otherwise, the signal is sent to all clients connected to the session.
-
-```php
-use OpenTok\OpenTok;
-
-// Send a signal to a specific client
-$signalPayload = array(
-    'data' => 'some signal message',
-    'type' => 'signal type'
-);
-$connectionId = 'da9cb410-e29b-4c2d-ab9e-fe65bf83fcaf';
-$opentok->signal($sessionId, $signalPayload, $connectionId);
-
-// Send a signal to everyone in the session
-$signalPayload = array(
-    'data' => 'some signal message',
-    'type' => 'signal type'
-);
-$opentok->signal($sessionId, $signalPayload);
-```
-
-For more information, see the [OpenTok signaling developer
-guide](https://tokbox.com/developer/guides/signaling/).
-
 ## Samples
 
 There are three sample applications included in this repository. To get going as fast as possible, clone the whole

phpdoc.dist.xml

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<phpdocumentor
+        configVersion="3"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xmlns="https://www.phpdoc.org"
+        xsi:noNamespaceSchemaLocation="https://docs.phpdoc.org/latest/phpdoc.xsd"
+>
+    <paths>
+        <output>docs</output>
+    </paths>
+    <version number="latest">
+        <api>
+            <source dsn=".">
+                <path>src</path>
+            </source>
+            <ignore hidden="true" symlinks="true">
+              <path>src/OpenTok/Util</path>
+            </ignore>
+        </api>
+    </version>
+</phpdocumentor>

src/OpenTok/Archive.php

@@ -218,7 +218,7 @@ public function toJson()
 
     /**
      * Adds a stream to a currently running archive that was started with the
-     * the <code>streamMode</code> set to <code>StreamMode.Manual</code>. You can call the method
+     * the streamMode set to StreamMode.Manual. You can call the method
      * repeatedly with the same stream ID, to toggle the stream's audio or video in the archive.
      * 
      * @param String $streamId The stream ID.
@@ -253,7 +253,7 @@ public function addStreamToArchive(string $streamId, bool $hasAudio, bool $hasVi
 
     /**
      * Removes a stream from a currently running archive that was started with the
-     * the <code>streamMode</code> set to <code>StreamMode.Manual</code>.
+     * the streamMode set to StreamMode.Manual.
      * 
      * @param String $streamId The stream ID.
      *

src/OpenTok/ArchiveList.php

@@ -67,6 +67,8 @@ public function totalCount()
 
     /**
      * Returns an array of Archive objects.
+     *
+     * @return Archive[]
      */
     public function getItems()
     {

src/OpenTok/Broadcast.php

@@ -165,7 +165,7 @@ public function updateLayout($layout)
 
     /**
      * Adds a stream to a currently running broadcast that was started with the
-     * the <code>streamMode</code> set to <code>StreamMode.Manual</code>. You can call the method
+     * the streamMode set to StreamMode.Manual. You can call the method
      * repeatedly with the same stream ID, to toggle the stream's audio or video in the broadcast.
      * 
      * @param String $streamId The stream ID.
@@ -200,7 +200,7 @@ public function addStreamToBroadcast(string $streamId, bool $hasAudio, bool $has
 
     /**
      * Removes a stream from a currently running broadcast that was started with the
-     * the <code>streamMode</code> set to <code>StreamMode.Manual</code>.
+     * the streamMode set to StreamMode.Manual.
      * 
      * @param String $streamId The stream ID.
      *

src/OpenTok/OpenTok.php

@@ -61,7 +61,9 @@ public function __construct($apiKey, $apiSecret, $options = array())
     }
 
     /**
-     * Creates a token for connecting to an OpenTok session. In order to authenticate a user
+     * Creates a token for connecting to an OpenTok session.
+     *
+     * In order to authenticate a user
      * connecting to an OpenTok session, the client passes a token when connecting to the session.
      * <p>
      * For testing, you generate tokens or by logging in to your
@@ -168,23 +170,23 @@ public function generateToken($sessionId, $options = array())
     *    will use to situate the session in its global network. If you do not set a location hint,
     *    the OpenTok servers will be based on the first client connecting to the session.</li>
     *
-    *     <li><code>'mediaMode'</code> (MediaMode) &mdash; Whether the session will transmit
-    *     streams using the OpenTok Media Router (<code>MediaMode.ROUTED</code>) or not
-    *     (<code>MediaMode.RELAYED</code>). By default, the <code>mediaMode</code> property
-    *     is set to <code>MediaMode.RELAYED</code>.
+    *    <li><code>'mediaMode'</code> (MediaMode) &mdash; Whether the session will transmit
+    *    streams using the OpenTok Media Router (<code>MediaMode.ROUTED</code>) or not
+    *    (<code>MediaMode.RELAYED</code>). By default, the <code>mediaMode</code> property
+    *    is set to <code>MediaMode.RELAYED</code>.
     *
-    *     <p>
-    *     With the <code>mediaMode</code> parameter set to <code>MediaMode.RELAYED</code>, the
-    *     session will attempt to transmit streams directly between clients. If clients cannot
-    *     connect due to firewall restrictions, the session uses the OpenTok TURN server to relay
-    *     audio-video streams.
+    *    <p>
+    *    With the <code>mediaMode</code> parameter set to <code>MediaMode.RELAYED</code>, the
+    *    session will attempt to transmit streams directly between clients. If clients cannot
+    *    connect due to firewall restrictions, the session uses the OpenTok TURN server to relay
+    *    audio-video streams.
     *
-    *     <p>
-    *     The
-    *     <a href="https://tokbox.com/opentok/tutorials/create-session/#media-mode" target="_top">
-    *     OpenTok Media Router</a> provides the following benefits:
+    *    <p>
+    *    The
+    *    <a href="https://tokbox.com/opentok/tutorials/create-session/#media-mode" target="_top">
+    *    OpenTok Media Router</a> provides the following benefits:
     *
-    *     <ul>
+    *    <ul>
     *       <li>The OpenTok Media Router can decrease bandwidth usage in multiparty sessions.
     *           (When the <code>mediaMode</code> parameter is set to <code>MediaMode.ROUTED</code>,
     *           each client must send a separate audio-video stream to each client subscribing to
@@ -197,7 +199,7 @@ public function generateToken($sessionId, $options = array())
     *       <li>The OpenTok Media Router supports the
     *         <a href="https://tokbox.com/opentok/tutorials/archiving" target="_top">archiving</a>
     *         feature, which lets you record, save, and retrieve OpenTok sessions.</li>
-    *     </ul>
+    *    </ul>
     *
     * </ul>
     *
@@ -304,7 +306,7 @@ public function createSession($options = array())
      *    archive are recorded to a single file (<code>OutputMode::COMPOSED</code>, the default)
      *    or to individual files (<code>OutputMode::INDIVIDUAL</code>).</li>
      *
-     * <ul>
+     * </ul>
      *
      * @return Archive The Archive object, which includes properties defining the archive, including
      * the archive ID.
@@ -415,7 +417,9 @@ public function deleteArchive($archiveId)
     }
 
     /**
-     * Returns an ArchiveList. The <code>items()</code> method of this object returns a list of
+     * Returns a list of archives for a session.
+     *
+     * The <code>items()</code> method of this object returns a list of
      * archives that are completed and in-progress, for your API key.
      *
      * @param integer $offset Optional. The index offset of the first archive. 0 is offset of the
@@ -453,7 +457,9 @@ public function setArchiveLayout(string $archiveId, Layout $layoutType): void
     }
 
     /**
-     * Sets the layout class list for streams in a session. Layout classes are used in
+     * Sets the layout class list for streams in a session.
+     *
+     * Layout classes are used in
      * the layout for composed archives and live streaming broadcasts. For more information, see
      * <a href="https://tokbox.com/developer/guides/archiving/layout-control.html">Customizing
      * the video layout for composed archives</a> and
@@ -496,7 +502,9 @@ public function forceDisconnect($sessionId, $connectionId)
      * Force the publisher of a specific stream to mute its published audio.
      *
      * <p>
-     * Also see the <a href="#method_forceMuteAll">OpenTok->forceMuteAll()</a> method.
+     * Also see the
+     * <a href="classes/OpenTok-OpenTok.html#method_forceMuteAll">OpenTok->forceMuteAll()</a>
+     * method.
      *
      * @param string $sessionId The OpenTok session ID containing the stream.
      *
@@ -525,10 +533,12 @@ public function forceMuteStream(string $sessionId, string $streamId): bool
      * <p>
      * In addition to existing streams, any streams that are published after the call to
      * this method are published with audio muted. You can remove the mute state of a session
-     * by calling the <a href="#method_disableForceMute">OpenTok->disableForceMute()</a> method.
-     *
+     * <a href="classes/OpenTok-OpenTok.html#method_disableForceMute">OpenTok->disableForceMute()</a>
+     * method.
      * <p>
-     * Also see the <a href="#method_forceMuteStream">OpenTok->forceMuteStream()</a> method.
+     * Also see the
+     * <a href="classes/OpenTok-OpenTok.html#method_forceMuteStream">OpenTok->forceMuteStream()</a>
+     * method.
      *
      * @param string $sessionId The OpenTok session ID.
      *
@@ -564,7 +574,8 @@ public function forceMuteAll(string $sessionId, array $options): bool
      * published to the session will no longer have audio muted.
      *
      * <p>
-     * After you call the <a href="#method_forceMuteAll">OpenTok->forceMuteAll()</a> method,
+     * After you call the
+     * <a href="classes/OpenTok-OpenTok.html#method_forceMuteAll">OpenTok->forceMuteAll()</a> method
      * any streams published after the call are published with audio muted. Call the
      * <c>disableForceMute()</c> method to remove the mute state of a session, so that
      * new published streams are not automatically muted.
@@ -603,8 +614,9 @@ public function disableForceMute(string $sessionId, array $options): bool
      *
      * @param String $sessionId The session ID of the session to be broadcast.
      *
-     * @param Array $options (Optional) An array with options for the broadcast. This array has
+     * @param array $options (Optional) An array with options for the broadcast. This array has
      * the following properties:
+     *
      * <ul>
      *   <li><code>layout</code> (Layout) &mdash; (Optional) An object defining the initial
      *     layout type of the broadcast. If you do not specify an initial layout type,
@@ -713,7 +725,9 @@ public function updateBroadcastLayout(string $broadcastId, Layout $layout): void
     }
 
     /**
-    * Sets the layout class list for a stream. Layout classes are used in
+    * Sets the layout class list for a stream.
+    *
+    * Layout classes are used in
     * the layout for composed archives and live streaming broadcasts.
     * <p>
     * For more information, see
@@ -725,7 +739,8 @@ public function updateBroadcastLayout(string $broadcastId, Layout $layout): void
     * <p>
     * You can set the initial layout class list for streams published by a client when you generate
     * the token used by the client to connect to the session. See the
-    * <a href="#method_generateToken">OpenTok->generateToken()</a> method.
+    * <a href="classes/OpenTok-OpenTok.html#method_generateToken">OpenTok::generateToken()</a>
+    * method.
     *
     * @param string $sessionId The session ID of the session the stream belongs to.
     *
@@ -812,8 +827,8 @@ public function listStreams($sessionId)
      * @param string $token The 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. Generate a token using the
-     * <a href="#method_generateToken">OpenTok->generateToken()</a> or
-     * <a href="OpenTok.Session.html#method_generateToken">Session->generateToken()</a>
+     * <a href="classes/OpenTok-OpenTok.html#method_generateToken">OpenTok::generateToken()</a> or
+     * <a href="classes/OpenTok-Session.html#method_generateToken">Session::generateToken()</a>
      * method.
      *
      * @param string $sipUri The SIP URI to be used as destination of the SIP Call initiated from
@@ -839,16 +854,16 @@ public function listStreams($sessionId)
      *    INVITE request for HTTP Digest authentication in case this is required by the Third Party
      *    SIP Platform.
      *
-     *     <ul>
+     *    <ul>
      *
-     *       <li><code>'username'</code> (string) &mdash; The username to be used
-     *       in the the SIP INVITE​ request for HTTP digest authentication (if one
-     *       is required).</li>
+     *    <li><code>'username'</code> (string) &mdash; The username to be used
+     *    in the the SIP INVITE​ request for HTTP digest authentication (if one
+     *    is required).</li>
      *
-     *       <li><code>'password'</code> (string) &mdash; The password to be used
-     *       in the the SIP INVITE​ request for HTTP digest authentication.</li>
+     *    <li><code>'password'</code> (string) &mdash; The password to be used
+     *    in the the SIP INVITE​ request for HTTP digest authentication.</li>
      *
-     *     </ul>
+     *    </ul>
      *
      *    <li><code>'secure'</code> (Boolean) &mdash; Indicates whether the media
      *    must be transmitted encrypted (true, the default) or not (false).</li>
@@ -869,7 +884,8 @@ public function listStreams($sessionId)
      * @return SipCall An object contains the OpenTok connection ID and stream ID
      * for the SIP call's connection in the OpenTok session. You can use the connection ID
      * to terminate the SIP call, using the
-     * <a href="#method_forceDisconnect">OpenTok->forceDisconnect()</a> method.
+     * <a href="classes/OpenTok-OpenTok.html#method_forceDisconnect">OpenTok::method_forceDisconnect()</a>
+     * method.
      */
     public function dial($sessionId, $token, $sipUri, $options = [])
     {

src/OpenTok/Role.php

@@ -22,7 +22,9 @@ abstract class Role extends BasicEnum
     /**
     * In addition to the privileges granted to a publisher, a moderator can perform
     * moderation functions, such as forcing clients to disconnect, to stop publishing streams,
-    * or to mute audio in published streams. See the
+    * or to mute audio in published streams.
+    *
+    * See the
     * <a href="https://tokbox.com/developer/guides/moderation/">Moderation developer guide</a>.
     */
     const MODERATOR = 'moderator';