Doxygen+Sphinx+Breathe = Inline Documentation

deanberris · deanberris · commit 86146c3f4fd8 · 2016-01-10T02:05:13.000+11:00
This is the initial attempt at getting inline documentation in the
project implementation into the sphinx-generated documentation. The way
we achieve this is by doing the following:

  - Add michaeljones/breathe as a submodule, making it simpler to
    generate the documentation with just Sphinx installed on the
    developer machine.
  - Define a Doxyfile configuration which generates HTML and XML
    documentation. The generated XML files are needed by Breathe to
    generate the HTML as part of the Sphinx docs generation process.
  - Update the documentation for the client type. This is a starting
    point showing how the generated docs are in-lined in the RST docs
    via breathe.
  - Wire up the documentation generation in the Sphinx configuration.

To generate the documentation now, we need two things installed on the
machine generating the docs: Sphinx and Doxygen. The steps involved are:

  1. cd cpp-netlib &amp;&amp; doxygen
  2. cd libs/network/doc/ &amp;&amp; make html

The results should be in libs/network/doc/_build/html, and the
generated HTML for the HTTP Client reference page should include the
doxygen-generated docs.
diff --git a/.gitignore b/.gitignore
@@ -11,3 +11,5 @@ libs/mime/test/mime-roundtrip
 _build
 /.project
 build/
+libs/network/doc/doxygen/
+.DS_Store
diff --git a/.gitmodules b/.gitmodules
@@ -4,3 +4,6 @@
 [submodule "deps/googlemock"]
 	path = deps/googlemock
 	url = https://github.com/google/googlemock.git
+[submodule "libs/network/doc/_ext/breathe"]
+	path = libs/network/doc/_ext/breathe
+	url = https://github.com/michaeljones/breathe.git
diff --git a/Doxyfile b/Doxyfile
diff --git a/boost/network/protocol/http/client.hpp b/boost/network/protocol/http/client.hpp
@@ -31,36 +31,49 @@ namespace boost {
 namespace network {
 namespace http {
 
+/**
+ * Basic Client API.
+ *
+ * This template defines an HTTP client object that is non-copyable and is
+ * implemented depending on the `Tag` parameter. It also hard-codes the version
+ * of HTTP to support.
+ *
+ * @tparam Tag The Tag type used to determine certain traits of the
+ *   implementation. We use the Tag as an input to other template metafunctions
+ *   to determine things like the string type, whether to use TCP or UDP for the
+ *   resolver, etc.
+ * @tparam version_major The HTTP major version.
+ * @tparam version_minor The HTTP minor version.
+ *
+ */
 template <class Tag, unsigned version_major, unsigned version_minor>
-struct basic_client : basic_client_facade<Tag, version_major, version_minor> {
- private:
+class basic_client : public basic_client_facade<Tag, version_major, version_minor> {
   typedef basic_client_facade<Tag, version_major, version_minor>
       base_facade_type;
 
  public:
-  typedef basic_request<Tag> request;
-  typedef basic_response<Tag> response;
-  typedef typename string<Tag>::type string_type;
   typedef Tag tag_type;
   typedef client_options<Tag> options;
 
-  // Constructors
-  // =================================================================
-  // This constructor takes a single options argument of type
-  // client_options. See boost/network/protocol/http/client/options.hpp
-  // for more details.
+  /**
+   * This constructor takes a single options argument of type
+   * client_options. See boost/network/protocol/http/client/options.hpp for
+   * more details.
+   */
   explicit basic_client(options const& options) : base_facade_type(options) {}
 
-  // This default constructor sets up the default options.
+  /** This default constructor sets up the default options. */
   basic_client() : base_facade_type(options()) {}
-  //
-  // =================================================================
 };
 
 #ifndef BOOST_NETWORK_HTTP_CLIENT_DEFAULT_TAG
 #define BOOST_NETWORK_HTTP_CLIENT_DEFAULT_TAG tags::http_async_8bit_udp_resolve
 #endif
 
+/**
+ * The default HTTP client type is an asynchronous UDP-resolving HTTP/1.1
+ * client.
+ */
 typedef basic_client<BOOST_NETWORK_HTTP_CLIENT_DEFAULT_TAG, 1, 1> client;
 
 }  // namespace http
diff --git a/boost/network/protocol/http/client/facade.hpp b/boost/network/protocol/http/client/facade.hpp
@@ -24,14 +24,37 @@ template <class Tag>
 struct basic_response;
 
 template <class Tag, unsigned version_major, unsigned version_minor>
-struct basic_client_facade {
-
+class basic_client_facade {
+  typedef basic_client_impl<Tag, version_major, version_minor> pimpl_type;
+ public:
+  /**
+   * The type to use for strings associated with this client. Typically resolves
+   * to `std::string`.
+   */
   typedef typename string<Tag>::type string_type;
+
+  /** The request type. This models the HTTP Request concept. */
   typedef basic_request<Tag> request;
+
+  /** The response type. This models the HTTP Response concept.*/
   typedef basic_response<Tag> response;
-  typedef basic_client_impl<Tag, version_major, version_minor> pimpl_type;
+
+  /**
+   * This callback is invoked with a range representing part of the response's
+   * body as it comes in. In case of errors, the second argument is an error
+   * code.
+   */
   typedef function<void(iterator_range<char const*> const&,
                         system::error_code const&)> body_callback_function_type;
+
+  /**
+   * Functions that model this signature will be used to generate part of the
+   * body while the request is being performed. This allows users to provide a
+   * generator function that will generate the body of the request piece-wise.
+   *
+   * Implementations should return `true` if there is more to the body of the
+   * request, and `false` otherwise.
+   */
   typedef function<bool(string_type&)> body_generator_function_type;
 
   explicit basic_client_facade(client_options<Tag> const& options) {
@@ -40,19 +63,49 @@ struct basic_client_facade {
 
   ~basic_client_facade() { pimpl->wait_complete(); }
 
+  /**
+   * Perform a HEAD request.
+   */
   response head(request const& request) {
     return pimpl->request_skeleton(request, "HEAD", false,
                                    body_callback_function_type(),
                                    body_generator_function_type());
   }
 
+  /**
+   * Perform a GET request.
+   *
+   * @param[in] request The request object including the URI and headers.
+   * @param[in] body_handler If provided, a callback invoked for parts of the
+   *   response's body.
+   * @returns A response object.
+   * @throw std::exception May throw exceptions on errors, derived from
+   *   `std::exception`.
+   */
   response get(request const& request,
                body_callback_function_type body_handler =
                    body_callback_function_type()) {
     return pimpl->request_skeleton(request, "GET", true, body_handler,
                                    body_generator_function_type());
   }
 
+  /**
+   * Perform a POST request.
+   *
+   * @param[in] request A copy of the request object including the URI and
+   *   headers.
+   * @param[in] body The whole contents of the body. If provided, this overrides
+   *   the body in the `request`.
+   * @param[in] content_type The content type for the request. This overrides
+   *   the content type in the `request`.
+   * @param[in] body_handler The callback invoked for parts of the response body
+   *   as they come in.
+   * @param[in] body_generator If provided, is invoked to generate parts of the
+   *   request's body as it is being sent.
+   * @returns A response object.
+   * @throws std::exception May throw exceptions on errors, derived from
+   *   `std::exception`.
+   */
   response post(request request, string_type const& body = string_type(),
                 string_type const& content_type = string_type(),
                 body_callback_function_type body_handler =
@@ -82,28 +135,82 @@ struct basic_client_facade {
                                    body_generator);
   }
 
+  /**
+   * Perform a POST request.
+   *
+   * @param[in] request The request including the URI and headers.
+   * @param[in] body_generator The function to call to generate part of the body
+   *   while the request is being performed.
+   * @param[in] callback If provided, the function to call for parts of the
+   *   response's body as they come in.
+   * @returns A response object.
+   * @throws std::exception May throw exceptions derived from std::exception in
+   *   case of errors.
+   */
   response post(request const& request,
                 body_generator_function_type body_generator,
-                body_callback_function_type callback =
-                    body_generator_function_type()) {
-    return pimpl->request_skeleton(request, "POST", true, callback,
-                                   body_generator);
+                body_callback_function_type body_handler =
+                    body_callback_function_type()) {
+    return pimpl->request_skeleton(request, "POST", true, body_handler,
+	body_generator);
   }
 
-  response post(request const& request, body_callback_function_type callback,
+  /**
+   * Perform a POST request.
+   *
+   * @param[in] request The request including the URI and headers.
+   * @param[in] body_generator The function to call to generate part of the body
+   *   while the request is being performed.
+   * @param[in] callback If provided, the function to call for parts of the
+   *   response's body as they come in.
+   * @returns A response object.
+   * @throws std::exception May throw exceptions derived from std::exception in
+   *   case of errors.
+   */
+  response post(request const& request, body_callback_function_type body_handler,
                 body_generator_function_type body_generator =
                     body_generator_function_type()) {
-    return post(request, string_type(), string_type(), callback,
-                body_generator);
+    return post(request, string_type(), string_type(), body_handler,
+	body_generator);
   }
 
+  /**
+   * Perform a POST request.
+   *
+   * @param[in] request The request object including the URI and headers.
+   * @param[in] body The whole contents of the body.
+   * @param[in] body_handler The callback invoked for parts of the response body
+   *   as they come in.
+   * @param[in] body_generator If provided, is invoked to generate parts of the
+   *   request's body as it is being sent.
+   * @returns A response object.
+   * @throws std::exception May throw exceptions on errors, derived from
+   *   `std::exception`.
+   */
   response post(request const& request, string_type const& body,
-                body_callback_function_type callback,
+                body_callback_function_type body_handler,
                 body_generator_function_type body_generator =
                     body_generator_function_type()) {
-    return post(request, body, string_type(), callback, body_generator);
+    return post(request, body, string_type(), body_handler, body_generator);
   }
 
+  /**
+   * Perform a PUT request.
+   *
+   * @param[in] request A copy of the request object including the URI and
+   *   headers.
+   * @param[in] body The whole contents of the body. If provided, this overrides
+   *   the body in the `request`.
+   * @param[in] content_type The content type for the request. This overrides
+   *   the content type in the `request`.
+   * @param[in] body_handler The callback invoked for parts of the response body
+   *   as they come in.
+   * @param[in] body_generator If provided, is invoked to generate parts of the
+   *   request's body as it is being sent.
+   * @returns A response object.
+   * @throws std::exception May throw exceptions on errors, derived from
+   *   `std::exception`.
+   */
   response put(request request, string_type const& body = string_type(),
                string_type const& content_type = string_type(),
                body_callback_function_type body_handler =
@@ -133,26 +240,62 @@ struct basic_client_facade {
                                    body_generator);
   }
 
+  /**
+   * Perform a PUT request.
+   *
+   * @param[in] request The request including the URI and headers.
+   * @param[in] callback If provided, the function to call for parts of the
+   *   response's body as they come in.
+   * @param[in] body_generator The function to call to generate part of the body
+   *   while the request is being performed.
+   * @returns A response object.
+   * @throws std::exception May throw exceptions derived from std::exception in
+   *   case of errors.
+   */
   response put(request const& request, body_callback_function_type callback,
                body_generator_function_type body_generator =
                    body_generator_function_type()) {
     return put(request, string_type(), string_type(), callback, body_generator);
   }
 
+  /**
+   * Perform a POST request.
+   *
+   * @param[in] request The request object including the URI and headers.
+   * @param[in] body The whole contents of the body.
+   * @param[in] body_handler The callback invoked for parts of the response body
+   *   as they come in.
+   * @param[in] body_generator If provided, is invoked to generate parts of the
+   *   request's body as it is being sent.
+   * @returns A response object.
+   * @throws std::exception May throw exceptions on errors, derived from
+   *   `std::exception`.
+   */
   response put(request const& request, string_type body,
-               body_callback_function_type callback,
-               body_generator_function_type body_generator =
-                   body_generator_function_type()) {
-    return put(request, body, string_type(), callback, body_generator);
+               body_callback_function_type body_handler,
+               body_generator_function_type body_generator = {}) {
+    return put(request, body, string_type(), body_handler, body_generator);
   }
 
+  /**
+   * Perform a DELETE request.
+   *
+   * @param[in] request The request object including the URI and the headers.
+   * @param[in] body_handler The callback invoked for parts of the response body
+   *   as they come in, if provided.
+   * @returns A response object.
+   * @throws std::exception May throw exceptions on errors, derived from
+   *   `std::exception`.
+   */
   response delete_(request const& request,
-                   body_callback_function_type body_handler =
-                       body_callback_function_type()) {
+                   body_callback_function_type body_handler = {}) {
     return pimpl->request_skeleton(request, "DELETE", true, body_handler,
                                    body_generator_function_type());
   }
 
+  /**
+   * Clears the cache of resolved endpoints.
+   */
   void clear_resolved_cache() { pimpl->clear_resolved_cache(); }
 
  protected:
diff --git a/boost/network/protocol/http/client/options.hpp b/boost/network/protocol/http/client/options.hpp
@@ -17,7 +17,8 @@ namespace network {
 namespace http {
 
 template <class Tag>
-struct client_options {
+class client_options {
+ public:
   typedef typename string<Tag>::type string_type;
 
   client_options()
diff --git a/boost/network/protocol/http/client/pimpl.hpp b/boost/network/protocol/http/client/pimpl.hpp
@@ -55,7 +55,7 @@ struct client_base<Tag, version_major, version_minor,
 }  // namespace impl
 
 template <class Tag, unsigned version_major, unsigned version_minor>
-struct basic_client;
+class basic_client;
 
 template <class Tag, unsigned version_major, unsigned version_minor>
 struct basic_client_impl
diff --git a/libs/network/doc/_ext/breathe b/libs/network/doc/_ext/breathe
@@ -0,0 +1 @@
+Subproject commit 853385ef4f0c3dd126887750e20d5f7456065998
diff --git a/libs/network/doc/conf.py b/libs/network/doc/conf.py
@@ -17,6 +17,9 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.append(os.path.abspath('_ext'))
+sys.path.append(os.path.abspath('_ext/breathe'))
+
+# Use breathe for doxygen integration
 
 # -- General configuration -----------------------------------------------------
 
@@ -27,10 +30,17 @@
               'sphinx.ext.autodoc',
               'sphinx.ext.doctest',
               'sphinx.ext.coverage',
+              'breathe',
               ]
 
 todo_include_todos = True
 
+# Tell breathe about the doxygen project.
+breathe_projects = { 'cppnetlib': os.path.abspath('doxygen/xml') }
+
+# Default breathe project
+breathe_default_project = 'cppnetlib'
+
 # Add any paths that contain templates here, relative to this directory.
 # templates_path = ['_templates']
 
@@ -70,7 +80,9 @@
 
 # List of directories, relative to source directory, that shouldn't be searched
 # for source files.
-exclude_trees = ['build', 'doxyxml', 'ext']
+exclude_trees = ['_build', 'doxygen', '_ext']
+
+exclude_patterns = ['_ext/breathe/*']
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
 # add_function_parentheses = True
diff --git a/libs/network/doc/reference/http_client.rst b/libs/network/doc/reference/http_client.rst
