Addressing review comments

2 files changed, 40 insertions, 19 deletions

diff --git a/docs/advanced-usage.rst b/docs/advanced-usage.rst
index db1efb97..e4782394 100644
--- a/docs/advanced-usage.rst
+++ b/docs/advanced-usage.rst
@@ -11,6 +11,8 @@ Streaming and IO
 When dealing with large responses it's often better to stream the response
 content::
 
+    >>> import urllib3
+    >>> http = urllib3.PoolManager()
     >>> r = http.request(
     ...     'GET',
     ...     'http://httpbin.org/bytes/1024',
@@ -97,9 +99,19 @@ Certificate validation and Mac OS X
 Apple-provided Python and OpenSSL libraries contain a patches that make them
 automatically check the system keychain's certificates. This can be
 surprising if you specify custom certificates and see requests unexpectedly
-succeed. See this
-`article <https://hynek.me/articles/apple-openssl-verification-surprises/>`_
-for more information.
+succeed. For example, if you are specifying your own certificate for validation
+and the server presents a different certificate you would expect the connection
+to fail. However, if that server presents a certificate that is in the system
+keychain then the conneciton will succeed.
+
+`This article <https://hynek.me/articles/apple-openssl-verification-surprises/>`_
+has more in-depth analysis and explanation.
+
+If you have `homebrew <http://brew.sh>`_, you can configure homebrew Python to
+use homebrew's OpenSSL instead of the system OpenSSL::
+
+    brew install openssl
+    brew install python --with-brewed-openssl
 
 .. _ssl_warnings:
 
diff --git a/docs/user-guide.rst b/docs/user-guide.rst
index 795b6968..e6b8c791 100644
--- a/docs/user-guide.rst
+++ b/docs/user-guide.rst
@@ -33,7 +33,8 @@ HTTP verb::
     ...     'http://httpbin.org/post',
     ...     fields={'hello: 'world'})
 
-The different types of requests you can send is covered in :ref:`request_data`.
+The :ref:`request_data` section covers sending other kinds of requests data,
+including JSON, files, and binary data.
 
 .. _response_content:
 
@@ -81,6 +82,20 @@ to a byte string representing the response content::
 Request data
 ------------
 
+Headers
+~~~~~~~
+
+You can specify headers as a dictionary in the ``headers`` argument in :meth:`~poolmanager.PoolManager.request`::
+
+    >>> r = http.request(
+    ...     'GET',
+    ...     'http://httpbin.org/headers',
+    ...     headers={
+    ...         'X-Something': 'value'
+    ...     })
+    >>> json.loads(r.data.decode('utf-8'))['headers']
+    {'X-Something': 'value', ...}
+
 Query parameters
 ~~~~~~~~~~~~~~~~
 
@@ -105,20 +120,6 @@ in the URL::
     >>> json.loads(r.data.decode('utf-8'))['args']
     {'arg': 'value'}
 
-Headers
-~~~~~~~
-
-You can specify headers as a dictionary in the ``headers`` argument in :meth:`~poolmanager.PoolManager.request`::
-
-    >>> r = http.request(
-    ...     'GET',
-    ...     'http://httpbin.org/headers',
-    ...     headers={
-    ...         'X-Something': 'value'
-    ...     })
-    >>> json.loads(r.data.decode('utf-8'))['headers']
-    {'X-Something': 'value', ...}
-
 
 .. _form_data:
 
@@ -172,7 +173,15 @@ approach as :ref:`form_data` and specify the file field as a tuple of
     {'filefield': '...'}
 
 While specifying the filename is not strictly required, it's recommended in
-order to match browser behavior.
+order to match browser behavior. You can also pass a third item in the tuple
+to specify the file's MIME type explicitly::
+
+    >>> r = http.request(
+    ...     'POST',
+    ...     'http://httpbin.org/post',
+    ...     fields={
+    ...         'filefield': ('example.txt', file_data, 'text/plain'),
+    ...     })
 
 For sending raw binary data simply specify the ``body`` argument. It's also
 recommended to set the ``Content-Type`` header::