Movatterモバイル変換


[0]ホーム

URL:


Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Sign up
Appearance settings

Doxygen+Sphinx+Breathe = Inline Documentation#582

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.

Already on GitHub?Sign in to your account

Merged
glynos merged 1 commit intocpp-netlib:masterfromdeanberris:initial-doxygen
Jan 12, 2016
Merged
Show file tree
Hide file tree
Changes fromall commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Doxygen+Sphinx+Breathe = Inline Documentation
This is the initial attempt at getting inline documentation in theproject implementation into the sphinx-generated documentation. The waywe 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 themachine generating the docs: Sphinx and Doxygen. The steps involved are:  1. cd cpp-netlib && doxygen  2. cd libs/network/doc/ && make htmlThe results should be in libs/network/doc/_build/html, and thegenerated HTML for the HTTP Client reference page should include thedoxygen-generated docs.
  • Loading branch information
@deanberris
deanberris committedJan 9, 2016
commit86146c3f4fd8f75dbf68998b21265d0140d3de9a
2 changes: 2 additions & 0 deletions.gitignore
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -11,3 +11,5 @@ libs/mime/test/mime-roundtrip
_build
/.project
build/
libs/network/doc/doxygen/
.DS_Store
3 changes: 3 additions & 0 deletions.gitmodules
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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
2,384 changes: 2,384 additions & 0 deletionsDoxyfile
View file
Open in desktop

Large diffs are not rendered by default.

39 changes: 26 additions & 13 deletionsboost/network/protocol/http/client.hpp
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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 singleoptions 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
Expand Down
179 changes: 161 additions & 18 deletionsboost/network/protocol/http/client/facade.hpp
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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) {
Expand All@@ -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 =
Expand DownExpand Up@@ -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_typecallback =
body_generator_function_type()) {
return pimpl->request_skeleton(request, "POST", true,callback,
body_generator);
body_callback_function_typebody_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_typecallback,
body_callback_function_typebody_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 =
Expand DownExpand Up@@ -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:
Expand Down
3 changes: 2 additions & 1 deletionboost/network/protocol/http/client/options.hpp
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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()
Expand Down
2 changes: 1 addition & 1 deletionboost/network/protocol/http/client/pimpl.hpp
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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
Expand Down
1 change: 1 addition & 0 deletionslibs/network/doc/_ext/breathe
Open in desktop
Submodulebreathe added at 853385
14 changes: 13 additions & 1 deletionlibs/network/doc/conf.py
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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 -----------------------------------------------------

Expand All@@ -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']

Expand DownExpand Up@@ -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
Expand Down
Loading

[8]ページ先頭

©2009-2025 Movatter.jp