Document the API better.

Author: Lukasa

hyper/http20/connection.py

@@ -32,6 +32,12 @@ def __init__(self, host, port=None, **kwargs):
 
         Most of the standard library's arguments to the constructor are
         irrelevant for HTTP/2.0 or not supported by hyper.
+
+        :param host: The host to connect to. This may be an IP address or a
+            hostname, and optionally may include a port: for example,
+            ``'twitter.com'``, ``'twitter.com:443'`` or ``'127.0.0.1'``.
+        :param port: (optional) The port to connect to. If not provided and one
+            also isn't provided in the ``host`` parameter, defaults to 443.
         """
         if port is None:
             try:
@@ -78,7 +84,12 @@ def request(self, method, url, body=None, headers={}):
         encodings, pass a bytes object. The Content-Length header is set to the
         length of the body field.
 
-        Returns a stream ID for the request.
+        :returns: A stream ID for the request.
+        :param method: The request method, e.g. ``'GET'``.
+        :param url: The URL to contact, e.g. ``'/path/segment'``.
+        :param body: (optional) The request body to send. Must be a bytestring
+            or a file-like object.
+        :param headers: (optional) The headers to send on the request.
         """
         stream_id = self.putrequest(method, url)
 
@@ -100,6 +111,10 @@ def getresponse(self, stream_id=None):
         the request whose response you want. Returns a HTTPResponse instance.
         If you pass no stream_id, you will receive the oldest HTTPResponse
         still outstanding.
+
+        :param stream_id: (optional) The stream ID of the request for which to
+            get a response.
+        :returns: A HTTP response object.
         """
         stream = (self.streams[stream_id] if stream_id is not None
                   else self.recent_stream)
@@ -109,6 +124,8 @@ def connect(self):
         """
         Connect to the server specified when the object was created. This is a
         no-op if we're already connected.
+
+        :returns: Nothing.
         """
         if self._sock is None:
             sock = socket.create_connection((self.host, self.port), 5)
@@ -131,6 +148,8 @@ def connect(self):
     def close(self):
         """
         Close the connection to the server.
+
+        :returns: Nothing.
         """
         # Todo: we should actually clean ourselves up if possible by sending
         # GoAway frames and closing all outstanding streams. For now this will
@@ -144,6 +163,10 @@ def putrequest(self, method, selector, **kwargs):
         This should be the first call for sending a given HTTP request to a
         server. It returns a stream ID for the given connection that should be
         passed to all subsequent request building calls.
+
+        :param method: The request method, e.g. ``'GET'``.
+        :param selector: The path selector.
+        :returns: A stream ID for the request.
         """
         # Create a new stream.
         s = self._new_stream()
@@ -170,6 +193,12 @@ def putheader(self, header, argument, stream_id=None):
         Unlike the httplib version of this function, this version does not
         actually send anything when called. Instead, it queues the headers up
         to be sent when you call ``endheaders``.
+
+        :param header: The name of the header.
+        :param argument: The value of the header.
+        :param stream_id: (optional) The stream ID of the request to add the
+            header to.
+        :returns: Nothing.
         """
         stream = (self.streams[stream_id] if stream_id is not None
                   else self.recent_stream)
@@ -186,6 +215,15 @@ def endheaders(self, message_body=None, final=False, stream_id=None):
         ``final`` argument is set to True, the stream will also immediately
         be closed: otherwise, the stream will be left open and subsequent calls
         to ``send()`` will be required.
+
+        :param message_body: (optional) The body to send. May not be provided
+            assuming that ``send()`` will be called.
+        :param final: (optional) If the ``message_body`` parameter is provided,
+            should be set to ``True`` if no further data will be provided via
+            calls to ``send()``.
+        :param stream_id: (optional) The stream ID of the request to finish
+            sending the headers on.
+        :returns: Nothing.
         """
         self.connect()
 
@@ -208,6 +246,13 @@ def send(self, data, final=False, stream_id=None):
         (excluding the normal HTTP/2.0 flow control rules). If this is the last
         data that will be sent as part of this request, the ``final`` argument
         should be set to ``True``. This will cause the stream to be closed.
+
+        :param data: The data to send.
+        :param final: (optional) Whether this is the last bit of data to be
+            sent on this request.
+        :param stream_id: (optional) The stream ID of the request to send the
+            data on.
+        :returns: Nothing.
         """
         stream = (self.streams[stream_id] if stream_id is not None
                   else self.recent_stream)

hyper/http20/response.py

@@ -94,6 +94,14 @@ def __init__(self, headers, stream):
     def read(self, amt=None, decode_content=True):
         """
         Reads the response body, or up to the next ``amt`` bytes.
+
+        :param amt: (optional) The amount of data to read. If not provided, all
+            the data will be read from the response.
+        :param decode_content: (optional) If ``True``, will transparently
+            decode the response data.
+        :returns: The read data. Note that if ``decode_content`` is set to
+            ``True``, the actual amount of data returned may be different to
+            the amount requested.
         """
         if amt is not None and amt <= len(self._data_buffer):
             data = self._data_buffer[:amt]
@@ -126,17 +134,24 @@ def getheader(self, name, default=None):
         value ``name``, return all of the values joined by ', '. If ``default``
         is any iterable other than a single string, its elements are similarly
         returned joined by commas.
+
+        :param name: The name of the header to get the value of.
+        :param default: (optional) The return value if the header wasn't sent.
+        :returns: The value of the header.
         """
         return self._headers.get(name, default)
 
     def getheaders(self):
         """
-        Return a list of (header, value) tuples.
+        Get all the headers sent on the response.
+
+        :returns: A list of (header, value) tuples.
         """
         return list(self._headers.items())
 
     def fileno(self):
         """
-        Return the ``fileno`` of the underlying socket.
+        Return the ``fileno`` of the underlying socket. This function is
+        currently not implemented.
         """
         pass