Update a bunch of documentation

Services/Twilio/NumberType.php

@@ -7,6 +7,20 @@ public function getResourceName($camelized = false) {
         return $camelized ? 'IncomingPhoneNumbers' : 'incoming_phone_numbers';
     }
 
+    /**
+     * Purchase a new phone number.
+     *
+     * Example usage:
+     *
+     * .. code-block:: php
+     *
+     *      $marlosBurner = '+14105551234';
+     *      $client->account->incoming_phone_numbers->local->purchase($marlosBurner);
+     *
+     * :param string $phone_number: The phone number to purchase
+     * :param array $params: An optional array of parameters to pass along with
+     *      the request (to configure the phone number)
+     */
     public function purchase($phone_number, array $params = array()) {
         $postParams = array(
             'PhoneNumber' => $phone_number

Services/Twilio/Rest/Call.php

@@ -1,19 +1,102 @@
 <?php
 
-class Services_Twilio_Rest_Call
-    extends Services_Twilio_InstanceResource
-{
-    public function hangup()
-    {
+/**
+ *   For more information, see the `Call Instance Resource <http://www.twilio.com/docs/api/rest/call#instance>`_ documentation.
+ *
+ *   .. php:attr:: sid
+ *
+ *      A 34 character string that uniquely identifies this resource.
+ *
+ *   .. php:attr:: parent_call_sid
+ *
+ *      A 34 character string that uniquely identifies the call that created this leg.
+ *
+ *   .. php:attr:: date_created
+ *
+ *      The date that this resource was created, given as GMT in RFC 2822 format.
+ *
+ *   .. php:attr:: date_updated
+ *
+ *      The date that this resource was last updated, given as GMT in RFC 2822 format.
+ *
+ *   .. php:attr:: account_sid
+ *
+ *      The unique id of the Account responsible for creating this call.
+ *
+ *   .. php:attr:: to
+ *
+ *      The phone number that received this call. e.g., +16175551212 (E.164 format)
+ *
+ *   .. php:attr:: from
+ *
+ *      The phone number that made this call. e.g., +16175551212 (E.164 format)
+ *
+ *   .. php:attr:: phone_number_sid
+ *
+ *      If the call was inbound, this is the Sid of the IncomingPhoneNumber that
+ *      received the call. If the call was outbound, it is the Sid of the
+ *      OutgoingCallerId from which the call was placed.
+ *
+ *   .. php:attr:: status
+ *
+ *      A string representing the status of the call. May be `QUEUED`, `RINGING`,
+ *      `IN-PROGRESS`, `COMPLETED`, `FAILED`, `BUSY` or `NO_ANSWER`.
+ *
+ *   .. php:attr:: stat_time
+ *
+ *      The start time of the call, given as GMT in RFC 2822 format. Empty if the call has not yet been dialed.
+ *
+ *   .. php:attr:: end_time
+ *
+ *      The end time of the call, given as GMT in RFC 2822 format. Empty if the call did not complete successfully.
+ *
+ *   .. php:attr:: duration
+ *
+ *      The length of the call in seconds. This value is empty for busy, failed, unanswered or ongoing calls.
+ *
+ *   .. php:attr:: price
+ *
+ *      The charge for this call in USD. Populated after the call is completed. May not be immediately available.
+ *
+ *   .. php:attr:: direction
+ *
+ *         A string describing the direction of the call. inbound for inbound
+ *         calls, outbound-api for calls initiated via the REST API or
+ *         outbound-dial for calls initiated by a <Dial> verb.
+ *
+ *   .. php:attr:: answered_by
+ *
+ *      If this call was initiated with answering machine detection, either human or machine. Empty otherwise.
+ *
+ *   .. php:attr:: forwarded_from
+ *
+ *        If this call was an incoming call forwarded from another number, the
+ *        forwarding phone number (depends on carrier supporting forwarding).
+ *        Empty otherwise.
+ *
+ *   .. php:attr:: caller_name
+ *
+ *      If this call was an incoming call from a phone number with Caller ID Lookup enabled, the caller's name. Empty otherwise.
+ */
+class Services_Twilio_Rest_Call extends Services_Twilio_InstanceResource {
+
+    /**
+     * Hang up the call
+     */
+    public function hangup() {
         $this->update('Status', 'completed');
     }
 
+    /**
+     * Redirect the call to a new URL
+     *
+     * :param string $url: the new URL to retrieve call flow from.
+     */
     public function route($url) {
         $this->update('Url', $url);
     }
 
-    protected function init($client, $uri)
-    {
+    protected function init($client, $uri) {
         $this->setupSubresources(
             'notifications',
             'recordings'

Services/Twilio/Rest/IncomingPhoneNumber.php

@@ -1,5 +1,90 @@
 <?php
 
+/**
+ *   An object representing a single phone number. For more
+ *   information, see the `IncomingPhoneNumber Instance Resource
+ *   <http://www.twilio.com/docs/api/rest/incoming-phone-numbers#instance>`_
+ *   documentation.
+ *
+ *   .. php:attr:: sid
+ *
+ *      A 34 character string that uniquely idetifies this resource.
+ *
+ *   .. php:attr:: date_created
+ *
+ *      The date that this resource was created, given as GMT RFC 2822 format.
+ *
+ *   .. php:attr:: date_updated
+ *
+ *      The date that this resource was last updated, given as GMT RFC 2822 format.
+ *
+ *   .. php:attr:: friendly_name
+ *
+ *      A human readable descriptive text for this resource, up to 64
+ *      characters long. By default, the FriendlyName is a nicely formatted
+ *      version of the phone number.
+ *
+ *   .. php:attr:: account_sid
+ *
+ *      The unique id of the Account responsible for this phone number.
+ *
+ *   .. php:attr:: phone_number
+ *
+ *      The incoming phone number. e.g., +16175551212 (E.164 format)
+ *
+ *   .. php:attr:: api_version
+ *
+ *      Calls to this phone number will start a new TwiML session with this
+ *      API version.
+ *
+ *   .. php:attr:: voice_caller_id_lookup
+ *
+ *      Look up the caller's caller-ID name from the CNAM database (additional charges apply). Either true or false.
+ *
+ *   .. php:attr:: voice_url
+ *
+ *      The URL Twilio will request when this phone number receives a call.
+ *
+ *   .. php:attr:: voice_method
+ *
+ *      The HTTP method Twilio will use when requesting the above Url. Either GET or POST.
+ *
+ *   .. php:attr:: voice_fallback_url
+ *
+ *      The URL that Twilio will request if an error occurs retrieving or executing the TwiML requested by Url.
+ *
+ *   .. php:attr:: voice_fallback_method
+ *
+ *      The HTTP method Twilio will use when requesting the VoiceFallbackUrl. Either GET or POST.
+ *
+ *   .. php:attr:: status_callback
+ *
+ *      The URL that Twilio will request to pass status parameters (such as call ended) to your application.
+ *
+ *   .. php:attr:: status_callback_method
+ *
+ *      The HTTP method Twilio will use to make requests to the StatusCallback URL. Either GET or POST.
+ *
+ *   .. php:attr:: sms_url
+ *
+ *      The URL Twilio will request when receiving an incoming SMS message to this number.
+ *
+ *   .. php:attr:: sms_method
+ *
+ *      The HTTP method Twilio will use when making requests to the SmsUrl. Either GET or POST.
+ *
+ *   .. php:attr:: sms_fallback_url
+ *
+ *      The URL that Twilio will request if an error occurs retrieving or executing the TwiML from SmsUrl.
+ *
+ *   .. php:attr:: sms_fallback_method
+ *
+ *      The HTTP method Twilio will use when requesting the above URL. Either GET or POST.
+ *
+ *   .. php:attr:: uri
+ *
+ *    The URI for this resource, relative to https://api.twilio.com.
+ */
 class Services_Twilio_Rest_IncomingPhoneNumber
     extends Services_Twilio_InstanceResource
 {

Services/Twilio/Rest/IncomingPhoneNumbers.php

@@ -1,8 +1,12 @@
 <?php
 
-class Services_Twilio_Rest_IncomingPhoneNumbers
-    extends Services_Twilio_ListResource
-{
+/**
+ * For more information, see the
+ * `IncomingPhoneNumbers API Resource
+ * <http://www.twilio.com/docs/api/rest/incoming-phone-numbers#local>`_
+ * documentation at twilio.com.
+ */
+class Services_Twilio_Rest_IncomingPhoneNumbers extends Services_Twilio_ListResource {
     function init($client, $uri) {
         $this->setupSubresources(
             'local',
@@ -24,12 +28,17 @@ function getList($type, array $params = array())
      * Return a phone number instance from its E.164 representation. If more
      * than one number matches the search string, returns the first one.
      *
-     * @param string $number The number in E.164 format, eg "+684105551234"
-     * @return Services_Twilio_Rest_IncomingPhoneNumber|null The number object,
-     *      or null
+     * Example usage:
      *
-     * @throws Services_Twilio_RestException if the number is invalid, not
-     *      provided in E.164 format or for any other API exception.
+     * .. code-block:: php
+     *
+     *      $number = $client->account->incoming_phone_numbers->getNumber('+14105551234');
+     *      echo $number->sid;
+     *
+     * :param string $number: The number in E.164 format, eg "+684105551234"
+     * :return:  A :php:class:`Services_Twilio_Rest_IncomingPhoneNumber` object, or null
+     * :raises: a A :php:class:`Services_Twilio_RestException` if the number is
+     *      invalid, not provided in E.164 format or for any other API exception.
      */
     public function getNumber($number) {
         $page = $this->getPage(0, 1, array(

Services/Twilio/Rest/Messages.php

@@ -31,10 +31,10 @@ public function create($params = array()) {
      *
      *      $client = new Services_Twilio('AC123', '123');
      *      $message = $client->account->messages->sendMessage(
-     *          '+14085551234', // From a Twilio number in your account
-     *          '+12125551234', // Text any number
+     *          '+14105551234', // From a Twilio number in your account
+     *          '+14105556789', // Text any number
      *          'Come at the king, you best not miss.'   // Message body (if any)
-     *          array('http://example.com/image.jpg'),   // An array of MediaUrls
+     *          array('https://demo.twilio.com/owl.png'),   // An array of MediaUrls
      *      );
      *
      * :param string $from: the from number for the message, this must be a