Clarify multipart documentation (#580)

*Clarify multipart behvaiour

diff --git a/docs/advanced.md b/docs/advanced.md
index bc1d0f8700b4de1b258383b9a801e613e60625a6..d087bd255e99fee4ca3024d396adeca1e94192c5 100644 (file)
--- a/docs/advanced.md
+++ b/docs/advanced.md
@@ -347,7 +347,7 @@ await httpx.get(url, timeout=timeout) # Does not timeout, returns after 10s
 
 As mentioned in the [quickstart](/quickstart#sending-multipart-file-uploads)
 multipart file encoding is available by passing a dictionary with the
-name of the payloads as keys and a tuple of elements as values.
+name of the payloads as keys and either tuple of elements or a file-like object or a string as values.
 
 ```python
 >>> files = {'upload-file': ('report.xls', open('report.xls', 'rb'), 'application/vnd.ms-excel')}
@@ -362,17 +362,17 @@ name of the payloads as keys and a tuple of elements as values.
 }
 ```
 
-More specifically, this tuple must have at least two elements and maximum of three:
+More specifically, if a tuple is used as a value, it must have between 2 and 3 elements:
 
-- The first one is an optional file name which can be set to `None`.
-- The second may be a file-like object or a string which will be automatically
+- The first element is an optional file name which can be set to `None`.
+- The second element may be a file-like object or a string which will be automatically
 encoded in UTF-8.
-- An optional third element can be included with the
+- An optional third element can be used to specify the 
 [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_Types)
-of the file being uploaded. If not specified HTTPX will attempt to guess the MIME type
-based on the file name specified as the first element or the tuple, if that
-is set to `None` or it cannot be inferred from it, HTTPX will default to
-`applicaction/octet-stream`.
+of the file being uploaded. If not specified HTTPX will attempt to guess the MIME type based
+on the file name, with unknown file extensions defaulting to "application/octet-stream".
+If the file name is explicitly set to `None` then HTTPX will not include a content-type
+MIME header field.
 
 ```python
 >>> files = {'upload-file': (None, 'text content', 'text/plain')}