document some popular methods

kevinburke · kevinburke · commit f8127827049e · 2011-12-22T17:35:40.000-08:00
diff --git a/docs/api/twiml.rst b/docs/api/twiml.rst
@@ -26,7 +26,7 @@ Primary Verbs
    :members:
 
 Secondary Verbs
-~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~
 
 .. autoclass:: twilio.twiml.Hangup
    :members:
diff --git a/docs/usage/conferences.rst b/docs/usage/conferences.rst
@@ -73,8 +73,6 @@ access the participants resource.
 Participants can be either muted or kicked out of the conference. The following
 code kicks out the first participants and mutes the rest.
 
-.. note::
-
 .. code-block:: python
 
     from twilio.rest import TwilioRestClient
diff --git a/twilio/rest/resources.py b/twilio/rest/resources.py
@@ -652,7 +652,29 @@ def create(self, to, from_, url, method=None, fallback_url=None,
                if_machine=None, send_digits=None, timeout=None,
                application_sid=None):
         """
-        Make a phone call to a number
+        Make a phone call to a number.
+
+        :param string to: The phone number to call
+        :param string `from_`: The caller ID (must be a verified Twilio number)
+        :param string url: The URL to read TwiML from when the call connects
+        :param method: The HTTP method Twilio should use to request the url
+        :type method: None (defaults to 'POST'), 'GET', or 'POST'
+        :param string fallback_url: A URL that Twilio will request if an error occurs requesting or executing the TwiML at url.
+        :param string fallback_method: The HTTP method that Twilio should use to request the fallback_url
+        :type fallback_method: None (will make a 'POST' request), 'GET', or 'POST'
+        :param string status_callback: A URL that Twilio will request when the call ends to notify your app.
+        :param string status_method: The HTTP method Twilio should use when requesting the above URL.
+        :param string if_machine: Tell Twilio to try and determine if a machine
+            (like voicemail) or a human has answered the call.
+            See more in our `answering machine documentation
+            <http://www.twilio.com/docs/api/rest/making_calls#handling-outcomes-answering-machines">`_.
+        :type if_machine: None, 'Continue', or 'Hangup'
+        :param string send_digits: A string of keys to dial after connecting to the number.
+        :type send_digits: None or any combination of (0-9), '#', '*' or 'w' (to insert a half second pause).
+        :param int timeout: The integer number of seconds that Twilio should allow the phone to ring before assuming there is no answer.
+        :param string application_sid: The 34 character sid of the application Twilio should use to handle this phone call. Should not be used in conjunction with the url parameter.
+
+        :return: An :class:`Call` object
         """
         params = transform_params({
             "To": to,
@@ -679,7 +701,7 @@ def update(self, sid, status=None, method=None, url=None):
         return self.update_instance(sid, params)
 
     def cancel(self, sid):
-        """ If this call is queued or ringing, cancel the call
+        """ If this call is queued or ringing, cancel the call.
         Will not affect in-progress calls.
 
         :param sid: A Call Sid for a specific call
@@ -817,7 +839,7 @@ def transfer(self, account_sid):
 
     def update(self, **kwargs):
         """
-        Update this phone number instance. 
+        Update this phone number instance.
         """
         a = self.parent.update(self.name, **kwargs)
         self.load(a.__dict__)
@@ -1024,10 +1046,11 @@ def create(self, to=None, from_=None, body=None, status_callback=None,
         """
         Create and send a SMS Message.
 
-        :param to: The destination phone number.
-        :param from_: The phone number sending this message.
-        :param body: The message you want to send, limited to 160 characters.
-        :param status_callback: URL that Twilio will update with message info
+        :param string to: The destination phone number.
+        :param string `from_`: The phone number sending this message (must be a verified Twilio number)
+        :param string body: The message you want to send, limited to 160 characters.
+        :param status_callback: A URL that Twilio will POST to when your message is processed.
+        :param string application_sid: The 34 character sid of the application Twilio should use to handle this phone call.
         """
         params = transform_params({
             "To": to,
@@ -1045,7 +1068,7 @@ def list(self, to=None, from_=None, before=None, after=None, **kwargs):
         paging informtion see :class:`ListResource`.
 
         :param to: Only show SMS messages to this phone number.
-        :param from_: Only show SMS messages from this phone number.
+        :param `from_`: Only show SMS messages from this phone number.
         :param date after: Only list recordings logged after this datetime
         :param date before: Only list recordings logged before this datetime
         """
@@ -1073,7 +1096,7 @@ class ShortCodes(ListResource):
     def list(self, short_code=None, friendly_name=None, **kwargs):
         """
         Returns a page of :class:`ShortCode` resources as a list. For
-        paging informtion see :class:`ListResource`.
+        paging information see :class:`ListResource`.
 
         :param short_code: Only show the ShortCode resources that match this
                            pattern. You can specify partial numbers and use '*'
@@ -1090,8 +1113,7 @@ def list(self, short_code=None, friendly_name=None, **kwargs):
     def update(self, sid, friendly_name=None, api_version=None, url=None,
                method=None, fallback_url=None, fallback_method=None):
         """
-        Returns a page of :class:`SMSMessage` resources as a list. For
-        paging informtion see :class:`ListResource`.
+        Update a specific :class:`ShortCode`, by specifying the sid.
 
         :param friendly_name: Description of the short code, with maximum
                               length 64 characters.
@@ -1271,7 +1293,7 @@ def create(self, friendly_name=None, api_version=None, voice_url=None,
                sms_url=None, sms_method=None, sms_fallback_url=None,
                sms_fallback_method=None, sms_status_callback=None):
         """
-        Update an :class:`Application` with any of these optional parameters.
+        Create an :class:`Application` with any of these optional parameters.
 
         :param friendly_name: A human readable description of the application,
                               with maximum length 64 characters.
