Use Doxygen-generated Documentation

deanberris · deanberris · commit 1e7c0e72dfcf · 2016-03-07T21:59:06.000-05:00
This allows us to use the doxygen docs as the canonical documentation
for the HTTP Client API. This removes a lot of the hand-written and
outdated documentation, and have documentation near the code instead.
diff --git a/libs/network/doc/reference/http_client.rst b/libs/network/doc/reference/http_client.rst
@@ -19,14 +19,6 @@ The HTTP clients all share the same API, but the internals are documented in
 terms of what is different and what to expect with the different
 implementations.
 
-As of 0.9.1 the default implementation for the :mod:`cpp-netlib` HTTP client is
-asynchronous.
-
-As of 0.11 the `Synchronous Clients`_ are now *DEPRECATED* and will be removed
-in subsequent releases.
-
-In 0.12.x the `Synchronous Clients`_ have been removed.
-
 Features
 --------
 
@@ -55,8 +47,8 @@ This dependency is imposed by `Boost.Asio`_
 .. _OpenSSL: http://www.openssl.org/
 .. _`Boost.Asio`: http://www.boost.org/libs/asio
 
-Implementations
----------------
+Client Implementation
+---------------------
 
 There is a single user-facing template class named ``basic_client`` which takes
 three template parameters:
@@ -69,14 +61,6 @@ three template parameters:
   * **http_version_minor** - an unsigned int that defines the HTTP minor version
     number.
 
-There are two major different class of implementations of the ``basic_client``
-template that depend on which tag you choose: `Synchronous Clients`_ and
-`Asynchronous Clients`_. These two different classes are described in their own
-sections following this one. What follows is a table of all tags supported by
-the HTTP client implementation provided by :mod:`cpp-netlib`.
-
----------------
-
 .. include:: ../in_depth/http_client_tags.rst
 
 In the above table the tags follow a pattern for describing the behavior
@@ -88,61 +72,24 @@ For example, the tag ``http_default_8bit_tcp_resolve`` indicates the protocol
 ``http``, a modifier ``default``, a character width of ``8bit``, and a resolve
 strategy of ``tcp_resolve``.
 
-Synchronous Clients
-~~~~~~~~~~~~~~~~~~~
-
-Of the client tags shown in the table, the following makes the ``basic_client``
-behave as a fully synchronous client.
-
-  * **http_default_8bit_tcp_resolve**
-  * **http_default_8bit_udp_resolve**
-  * **http_keepalive_8bit_tcp_resolve**
-  * **http_keepalive_8bit_udp_resolve**
-
-The synchronous client implements all the operations of the client underneath
-the interface all block to wait for I/O to finish. All the member methods are
-synchronous and will block until the response object is ready or throws if errors
-are encountered in the performance of the HTTP requests.
-
-.. warning:: The synchronous clients are **NOT** thread safe. You will need to do
-   external synchronization to use synchronous client implementations.
-
-.. note:: As of version 0.11, all the synchronous client implementations are
-   deprecated. They will be removed in the next version of the library.
-
-Asynchronous Clients
-~~~~~~~~~~~~~~~~~~~~
+The  client is implemented as an `Active Object`_. This means that the client
+has and manages its own lifetime thread, and returns values that are
+asynchronously filled in. The response object encapsulates futures which get
+filled in once the values are available.
 
-The following tags specify the ``basic_client`` to behave in an asynchronous
-manner:
-
-  * **http_async_8bit_tcp_resolve**
-  * **http_async_8bit_udp_resolve**
-
-An asynchronous client implementation means that``basic_client<...>`` is an
-`Active Object`_. This means that the client has and manages its own lifetime
-thread, and returns values that are asynchronously filled in. The response
-object encapsulates Boost.Thread_ futures which get filled in once the values
-are available.
-
-.. _Boost.Thread: http://www.boost.org/libs/thread
 .. _`Active Object`: http://en.wikipedia.org/wiki/Active_object
 
-The asynchronous clients implement all operations asynchronously which are hidden
-from the user. The interface is still synchronous but the fetching of data
-happens on a different thread.
+.. note:: The client objects are thread safe, and can be shared across many
+   threads. Each request starts a sequence of asynchronous operations dedicated
+   to that request. The client does not re-cycle connections and uses a
+   one-request-one-connection model.
 
-.. note:: The asynchronous clients are thread safe, and can be shared across
-   many threads. Each request starts a sequence of asynchronous operations
-   dedicated to that request. The client does not re-cycle connections and uses
-   a one-request-one-connection model.
-
-When an asynchronous client object is destroyed, it waits for all pending
-asynchronous operations to finish. Errors encountered during operations on
-retrieving data from the response objects cause exceptions to be thrown --
-therefore it is best that if a client object is constructed, it should outlive
-the response object or be outside the try-catch block handling the errors from
-operations on responses. In code, usage should look like the following:
+When a client object is destroyed, it waits for all pending asynchronous
+operations to finish. Errors encountered during operations on retrieving data
+from the response objects cause exceptions to be thrown -- therefore it is best
+that if a client object is constructed, it should outlive the response object
+or be outside the try-catch block handling the errors from operations on
+responses. In code, usage should look like the following:
 
 .. code-block:: c++
 
@@ -180,15 +127,6 @@ Also, that code using the HTTP client will have use the following header:
 
     #include <boost/network/include/http/client.hpp>
 
-.. note:: Starting version 0.9, cpp-netlib clients and server implementations
-   by default now have an externally-linked component. This is a breaking change
-   for code that used to rely on cpp-netlib being a header-only library, but can
-   inhibited by defining the ``BOOST_NETWORK_NO_LIB`` preprocessor macro before
-   including any cpp-netlib header.
-
-.. note:: Starting version 0.11, cpp-netlib clients and server implementations
-   no longer support the ``BOOST_NETWORK_NO_LIB`` option.
-
 Constructors
 ~~~~~~~~~~~~
 
@@ -201,56 +139,12 @@ initialization.
     Constructor taking a ``client_options<Tag>`` object. The following table
     shows the options you can set on a ``client_options<Tag>`` instance.
 
-+--------------------------+----------------------------+--------------------------+
-| Parameter Name           | Type                       | Description              |
-+==========================+============================+==========================+
-| follow_redirects         | ``bool``                   | Boolean to specify       |
-|                          |                            | whether the client       |
-|                          |                            | should follow HTTP       |
-|                          |                            | redirects. Default is    |
-|                          |                            | ``false``.               |
-+--------------------------+----------------------------+--------------------------+
-| cache_resolved           | ``bool``                   | Boolean to specify       |
-|                          |                            | whether the client       |
-|                          |                            | should cache resolved    |
-|                          |                            | endpoints. The default   |
-|                          |                            | is ``false``.            |
-+--------------------------+----------------------------+--------------------------+
-| io_service               | ``shared_ptr<io_service>`` | Shared pointer to a      |
-|                          |                            | Boost.Asio               |
-|                          |                            | ``io_service``.          |
-+--------------------------+----------------------------+--------------------------+
-| openssl_certificate      | ``string``                 | The filename of the      |
-|                          |                            | certificate to load for  |
-|                          |                            | the SSL connection for   |
-|                          |                            | verification.            |
-+--------------------------+----------------------------+--------------------------+
-| openssl_verify_path      | ``string``                 | The directory from       |
-|                          |                            | which the certificate    |
-|                          |                            | authority files are      |
-|                          |                            | located.                 |
-+--------------------------+----------------------------+--------------------------+
-| always_verify_peer       | ``bool``                   | Boolean to specify       |
-|                          |                            | whether the client       |
-|                          |                            | should always verify     |
-|                          |                            | peers in SSL connections |
-+--------------------------+----------------------------+--------------------------+
-| openssl_certificate_file | ``string``                 | Filename of the          |
-|                          |                            | certificate to use for   |
-|                          |                            | client-side SSL session  |
-|                          |                            | establishment.           |
-+--------------------------+----------------------------+--------------------------+
-| openssl_private_key_file | ``string``                 | Filename of the          |
-|                          |                            | private key to use for   |
-|                          |                            | client-side SSL session  |
-|                          |                            | establishment.           |
-+--------------------------+----------------------------+--------------------------+
-| timeout                  | ``int``                    | Number of seconds to     |
-|                          |                            | wait for client requests |
-|                          |                            | before considering a     |
-|                          |                            | timeout has occurred.    |
-+--------------------------+----------------------------+--------------------------+
+Client Options
+~~~~~~~~~~~~~~
 
+.. doxygenclass:: boost::network::http::client_options
+   :project: cppnetlib
+   :members:
 
 To use the above supported named parameters, you'll have code that looks like
 the following:
@@ -284,144 +178,14 @@ and that there is an appropriately constructed response object named
     client::request request_("http://cpp-netib.github.com/");
     client::response response_;
 
-``response_ = client_.get(request_)``
-    Perform an HTTP GET request.
-``response_ = client_.get(request_, callback)``
-    Perform an HTTP GET request, and have the body chunks be handled by the
-    ``callback`` parameter. The signature of ``callback`` should be the following:
-    ``void(iterator_range<char const *> const &, boost::system::error_code const
-    &)``.
-``response_ = client_.head(request_)``
-    Perform an HTTP HEAD request.
-``response_ = client_.post(request_)``
-    Perform an HTTP POST, use the data already set in the request object which
-    includes the headers, and the body.
-``response_ = client_.post(request_, callback)``
-    Perform an HTTP POST request, and have the body chunks be handled by the
-    ``callback`` parameter. The signature of ``callback`` should be the following:
-    ``void(iterator_range<char const *> const &, boost::system::error_code const
-    &)``.
-``response_ = client_.post(request_, body)``
-    Body is a string of type ``boost::network::string<Tag>::type`` where ``Tag``
-    is the HTTP Client's ``Tag``. The default content-type used is
-    ``x-application/octet-stream``.
-``response_ = client_.post(request_, body, callback)``
-    Body is a string of type ``boost::network::string<Tag>::type`` where ``Tag``
-    is the HTTP Client's ``Tag``. The default content-type used is
-    ``x-application/octet-stream``. Have the response body chunks be handled by
-    the ``callback`` parameter. The signature of ``callback`` should be the
-    following: ``void(iterator_range<char const *> const &,
-    boost::system::error_code const &)``.
-``response_ = client_.post(request_, body, content_type)``
-    The body and content_type parameters are of type
-    ``boost::network::string<Tag>::type`` where ``Tag`` is the HTTP Client's
-    ``Tag``. This uses the request object's other headers.
-``response_ = client_.post(request_, body, content_type, callback)``
-    The body and content_type parameters are of type
-    ``boost::network::string<Tag>::type`` where ``Tag`` is the HTTP Client's
-    ``Tag``. This uses the request object's other headers. Have the response
-    body chunks be handled by the ``callback`` parameter. The signature of
-    ``callback`` should be the following: ``void(iterator_range<char const *> const
-    &, boost::system::error_code const &)``.
-``response_ = client_.post(request_, body, content_type, callback, streaming_callback)``
-    The body and content_type parameters are of type
-    ``boost::network::string<Tag>::type`` where ``Tag`` is the HTTP Client's
-    ``Tag``. This uses the request object's other headers. Have the response
-    body chunks be handled by the ``callback`` parameter. The signature of
-    ``callback`` should be the following: ``void(iterator_range<char const *> const
-    &, boost::system::error_code const &)``. The ``streaming_callback``
-    argument should have a which has a signature of the form:
-    ``bool(string_type&)``. The provided ``string_type&`` will be streamed as
-    soon as the function returns. A return value of ``false`` signals the
-    client that the most recent invocation is the last chunk to be sent.
-``response_ = client_.post(request_, streaming_callback)``
-    Perform and HTTP POST request, and have the request's body chunks be
-    generated by the ``streaming_callback`` which has a signature of the form:
-    ``bool(string_type&)``. The provided ``string_type&`` will be streamed as
-    soon as the function returns. A return value of ``false`` signals the client
-    that the most recent invocation is the last chunk to be sent.
-``response_ = client_.post(request_, callback, streaming_callback)``
-    Perform an HTTP POST request, and have the body chunks be handled by the
-    ``callback`` parameter. The signature of ``callback`` should be the
-    following: ``void(iterator_range<char const *> const &,
-    boost::system::error_code const &)``. This form also has the request's body
-    chunks be generated by the ``streaming_callback`` which has a signature of
-    the form: ``bool(string_type&)``. The provided ``string_type&`` will be
-    streamed as soon as the function returns. A return value of ``false``
-    signals the client that the most recent invocation is the last chunk to be
-    sent.
-``response_ = client_.put(request_)``
-    Perform an HTTP PUT, use the data already set in the request object which
-    includes the headers, and the body.
-``response_ = client_.put(request_, callback)``
-    Perform an HTTP PUT request, and have the body chunks be handled by the
-    ``callback`` parameter. The signature of ``callback`` should be the following:
-    ``void(iterator_range<char const *> const &, boost::system::error_code const
-    &)``.
-``response_ = client_.put(request_, body)``
-    Body is a string of type ``boost::network::string<Tag>::type`` where ``Tag``
-    is the HTTP Client's ``Tag``. The default content-type used is
-    ``x-application/octet-stream``.
-``response_ = client_.put(request_, body, callback)``
-    Body is a string of type ``boost::network::string<Tag>::type`` where ``Tag``
-    is the HTTP Client's ``Tag``. The default content-type used is
-    ``x-application/octet-stream``. Have the response body chunks be handled by
-    the ``callback`` parameter. The signature of ``callback`` should be the
-    following: ``void(iterator_range<char const *> const &,
-    boost::system::error_code const &)``.
-``response_ = client_.put(request_, body, content_type)``
-    The body and content_type parameters are of type
-    ``boost::network::string<Tag>::type`` where ``Tag`` is the HTTP Client's
-    ``Tag``. This uses the request object's other headers.
-``response_ = client_.put(request_, body, content_type, callback)``
-    The body and content_type parameters are of type
-    ``boost::network::string<Tag>::type`` where ``Tag`` is the HTTP Client's
-    ``Tag``. This uses the request object's other headers. Have the response
-    body chunks be handled by the ``callback`` parameter. The signature of
-    ``callback`` should be the following: ``void(iterator_range<char const *> const
-    &, boost::system::error_code const &)``.
-``response_ = client_.put(request_, body, content_type, callback, streaming_callback)``
-    The body and content_type parameters are of type
-    ``boost::network::string<Tag>::type`` where ``Tag`` is the HTTP Client's
-    ``Tag``. This uses the request object's other headers. Have the response
-    body chunks be handled by the ``callback`` parameter. The signature of
-    ``callback`` should be the following: ``void(iterator_range<char const *> const
-    &, boost::system::error_code const &)``. This form also has the request's body
-    chunks be generated by the ``streaming_callback`` which has a signature of
-    the form: ``bool(string_type&)``. The provided ``string_type&`` will be
-    streamed as soon as the function returns. A return value of ``false``
-    signals the client that the most recent invocation is the last chunk to be
-    sent
-``response_ = client_.put(request_, streaming_callback)``
-    Perform and HTTP PUT request, and have the request's body chunks be
-    generated by the ``streaming_callback`` which has a signature of the form:
-    ``bool(string_type&)``. The provided ``string_type&`` will be streamed as
-    soon as the function returns. A return value of ``false`` signals the client
-    that the most recent invocation is the last chunk to be sent.
-``response_ = client_.put(request_, callback, streaming_callback)``
-    Perform an HTTP PUT request, and have the body chunks be handled by the
-    ``callback`` parameter. The signature of ``callback`` should be the
-    following: ``void(iterator_range<char const *> const &,
-    boost::system::error_code const &)``. This form also has the request's body
-    chunks be generated by the ``streaming_callback`` which has a signature of
-    the form: ``bool(string_type&)``. The provided ``string_type&`` will be
-    streamed as soon as the function returns. A return value of ``false``
-    signals the client that the most recent invocation is the last chunk to be
-    sent.
-``response_ = client_.delete_(request_)``
-    Perform an HTTP DELETE request.
-``response_ = client_.delete_(request_, body_handler=callback)``
-    Perform an HTTP DELETE request, and have the response body chunks be handled
-    by the ``callback`` parameter. The signature of ``callback`` should be the
-    following: ``void(iterator_range<char const *> const &,
-    boost::system::error_code const &)``.
-
-Client-Specific
-~~~~~~~~~~~~~~~
-
-``client_.clear_resolved_cache()``
-    Clear the cache of resolved endpoints.
 
+.. doxygenclass:: boost::network::http::basic_client
+   :project: cppnetlib
+   :members:
+   :undoc-members:
+
+.. doxygentypedef:: boost::network::http::client
+   :project: cppnetlib
 
 Streaming Body Handler
 ~~~~~~~~~~~~~~~~~~~~~~
@@ -475,19 +239,3 @@ to create a function object.
 
 The ``BOOST_NETWORK_HTTP_BODY_CALLBACK`` macro is defined in
 ``boost/network/protocol/http/client/macros.hpp``.
-
-Generated Documentation
------------------------
-
-.. doxygenclass:: boost::network::http::client_options
-   :project: cppnetlib
-   :members:
-   :undoc-members:
-
-.. doxygenclass:: boost::network::http::basic_client
-   :project: cppnetlib
-   :members:
-   :undoc-members:
-
-.. doxygentypedef:: boost::network::http::client
-   :project: cppnetlib
