Add documentation

docs/api/rest.rst

@@ -468,13 +468,30 @@ Participant
 
       The URI for this resource, relative to https://api.twilio.com.
 
+IncomingPhoneNumbers
+========================
+
+.. php:class:: Services_Twilio_Rest_IncomingPhoneNumbers
+
+   For more information, see the `IncomingPhoneNumbers API Resource <http://www.twilio.com/docs/api/rest/incoming-phone-numbers#local>`_ documentation at twilio.com.
+
+   .. php:method:: getNumber($number)
+
+    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: A :php:class:`Services_Twilio_Rest_IncomingPhoneNumber` object, or null
 
-PhoneNumber
+IncomingPhoneNumber
 =================
 
 .. php:class:: Services_Twilio_Rest_IncomingPhoneNumber
 
-   For more information, see the `IncomingPhoneNumber Instance Resource <http://www.twilio.com/docs/api/rest/incoming-phone-numbers#instance>`_ documentation.
+   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
 

docs/usage/rest/phonenumbers.rst

@@ -22,7 +22,7 @@ First, we need to search for an available phone number. Use the
         echo 'Number: ' + $number->phone_number + "\n";
     }
     
-You can also pass in parameters, to search for phone numbers in a certain area
+You can also pass in parameters to search for phone numbers in a certain area
 code, or which contain a certain pattern.
 
 .. code-block:: php
@@ -45,7 +45,6 @@ Buying a Number
 Once you have a phone number, purchase it by creating a new
 :php:class:`Services_Twilio_Rest_IncomingPhoneNumber` instance.
 
-
 .. code-block:: php
 
     $accountSid = 'AC1234567890abcdef1234567890a';
@@ -88,6 +87,38 @@ You can also purchase a random number with a given area code (US/Canada only):
 
     echo $purchasedNumber->sid;
 
+Retrieving All of a Number's Properties
+---------------------------------------
+
+If you know the number and you want to retrieve all of the properties of that
+number, such as the ``voice_url`` or the ``sms_method``, you can use the
+:php:meth:`Services_Twilio_Rest_IncomingPhoneNumbers::getNumber` convenience
+function.
+
+.. code-block:: php
+
+    $accountSid = 'AC1234567890abcdef1234567890a';
+    $authToken = 'abcdef1234567890abcdefabcde9';
+
+    $client = new Services_Twilio($accountSid, $authToken);
+
+    // Number must be in e.164 format.
+    $number = $client->account->incoming_phone_numbers->getNumber('+14105551234');
+    echo $number->voice_url;
+
+If you know the ``sid`` of a phone number, you can retrieve it using the
+``get()`` function.
+
+.. code-block:: php
+
+    $accountSid = 'AC1234567890abcdef1234567890a';
+    $authToken = 'abcdef1234567890abcdefabcde9';
+
+    $client = new Services_Twilio($accountSid, $authToken);
+
+    $number = $client->account->incoming_phone_numbers->get('PN123456');
+    echo $number->voice_url;
+
 Updating a Number
 -----------------