Add documentation

.gitignore

 /build*/
+/generated-docs/
 .cache/
 .ccls-cache/
 .exrc

.gitlab-ci.yml

@@ -66,3 +66,41 @@ build-hunter:
   script:
     - cmake -GNinja -S . -B build -DHUNTER_ENABLED=ON
     - ninja -C build
+
+test-pages:
+  stage: build
+  tags: [docker]
+  image: alpine
+  except:
+    - master
+  needs: []
+  before_script:
+    - apk update
+    - apk add doxygen git texlive-full py3-jinja2 py3-pygments
+    #- git clone git://github.com/mosra/m.css
+    - git clone  --single-branch -b fix-class-parsed-as-function git://github.com/crisluengo/m.css
+  script:
+    - ./m.css/documentation/doxygen.py Doxyfile-mcss
+    - mv generated-docs/html/ public/
+  artifacts:
+    paths:
+      - public
+
+pages:
+  stage: build
+  tags: [docker]
+  image: alpine
+  only:
+    - master
+  needs: []
+  before_script:
+    - apk update
+    - apk add doxygen git texlive-full py3-jinja2 py3-pygments
+    #- git clone git://github.com/mosra/m.css
+    - git clone  --single-branch -b fix-class-parsed-as-function git://github.com/crisluengo/m.css
+  script:
+    - ./m.css/documentation/doxygen.py Doxyfile-mcss
+    - mv generated-docs/html/ public/
+  artifacts:
+    paths:
+      - public

Doxyfile-mcss

+@INCLUDE                = Doxyfile
+GENERATE_HTML           = NO
+GENERATE_XML            = YES
+XML_PROGRAMLISTING      = NO

README.md

 coeurl
 ======
 
+[TOC]
+
 Simple library to do http requests asynchronously via CURL in C++. (Eventually
 as coroutines, once all the compilers I need to support support them.)
 
@@ -10,11 +12,11 @@ example](https://curl.se/libcurl/c/hiperfifo.html).
 You can do a get request with 3 simple steps:
 
 1. Initialize the library:
-```c++
+```cpp
 coeurl::Client g{};
 ```
 2. Do a request
-```c++
+```cpp
 g.get("http://localhost:5000/", [](const coeurl::Request &res) {
     std::cout << res.response() << std::endl;
 });
@@ -33,6 +35,20 @@ Dependencies
 - spdlog
 - for tests: doctest
 
+Building
+--------
+
+Usually meson should do all you need. For example you can build it like this in
+a subdirectory called `buildir/`:
+
+```sh
+meson setup builddir
+meson compile -C builddir
+```
+
+There is also a cmake file, but this does not properly support installation. It
+is only useful for using this project via ExternalProject.
+
 Limitations
 -----------
 
@@ -56,3 +72,4 @@ Interesting bits
 		query the Request once it has completed for the headers, status code, etc.
 - Don't modify the Request while it is in flight or call any members on it until
 		it is completed, after you submitted it.
+

docs/dirs.dox

+/// @dir include
+/// @brief Include directory. Add this to your include path.
+
+/// @dir include/coeurl
+/// @brief The root directory for all the classes part of the public API.
+
+/// @example examples/coeurl.cpp

include/coeurl/client.hpp

 #pragma once
 
+/// @file
+/// @brief Include for the @ref coeurl::Client
+
 #include <atomic>
 #include <functional>
 #include <map>
@@ -16,47 +19,126 @@
 
 #include "headers.hpp"
 
+/// @namespace coeurl
+/// @brief Namespace for all public @ref coeurl classes
 namespace coeurl {
 struct Request;
 struct SockInfo;
 
-/* Global information, common to all connections */
+//! Global information, common to all connections
 struct Client {
+    //! construct a new client
     Client();
+    /// @brief cleans up a client
+    /// Implicitly closes the connection and blocks until all of them exited.
     ~Client();
 
+    //! Uncopyable
     Client(Client const &) = delete;
+    //! Uncopyable
     void operator=(Client const &) = delete;
+    //! Unmoveable
     Client(Client &&) = delete;
+    //! Unmoveable
     void operator=(Client &&) = delete;
 
-    // submit a manually created request
+    //! Submit a manually created request
     void submit_request(std::shared_ptr<Request> conn);
-    // Stop all currently running requests
+    //! Stop all currently running requests
     void shutdown();
-    // Stop the event loop. If you force close it, all pending requests are
-    // cancelled.
+    //! Stop the event loop. If you force close it, all pending requests are
+    //! cancelled.
     void close(bool force = false);
 
-    // make a simple get request. For more complicated requests, create it
-    // manually and call submit_request.
+    /// @brief Make a simple GET request.
+    /// For more complicated requests, create it manually and call submit_request.
+    /// @param url The url to request.
+    /// @param callback The callback, which will be called after the request is
+    /// completed. The request will be passed as a parameter, which you can use
+    /// to access the response.
+    /// @param headers Headers to use for this request. Defaults to none.
+    /// @param max_redirects How many redirects to follow. Defaults to none.
     void get(std::string url, std::function<void(const Request &)> callback, const Headers &headers = {},
              long max_redirects = 0);
+
+    /// @brief Make a simple DELETE request.
+    /// @param url The url to request.
+    /// @param callback The callback, which will be called after the request is
+    /// completed. The request will be passed as a parameter, which you can use
+    /// to access the response.
+    /// @param headers Headers to use for this request. Defaults to none.
+    /// @param max_redirects How many redirects to follow. Defaults to none.
     void delete_(std::string url, std::function<void(const Request &)> callback, const Headers &headers = {},
                  long max_redirects = 0);
+
+    /// @brief Make a simple DELETE request with a body.
+    /// @param url The url to request.
+    /// @param request_body The body to use with this request.
+    /// @param mimetype The mimetype of the @a request_body.
+    /// @param callback The callback, which will be called after the request is
+    /// completed. The request will be passed as a parameter, which you can use
+    /// to access the response.
+    /// @param headers Headers to use for this request. Defaults to none.
+    /// @param max_redirects How many redirects to follow. Defaults to none.
     void delete_(std::string url, std::string request_body, std::string mimetype,
                  std::function<void(const Request &)> callback, const Headers &headers = {}, long max_redirects = 0);
+
+    /// @brief Make a simple HEAD request.
+    /// For more complicated requests, create it manually and call submit_request.
+    /// @param url The url to request.
+    /// @param callback The callback, which will be called after the request is
+    /// completed. The request will be passed as a parameter, which you can use
+    /// to access the response.
+    /// @param headers Headers to use for this request. Defaults to none.
+    /// @param max_redirects How many redirects to follow. Defaults to none.
     void head(std::string url, std::function<void(const Request &)> callback, const Headers &headers = {},
               long max_redirects = 0);
+
+    /// @brief Make a simple OPTIONS request.
+    /// For more complicated requests, create it manually and call submit_request.
+    /// @param url The url to request.
+    /// @param callback The callback, which will be called after the request is
+    /// completed. The request will be passed as a parameter, which you can use
+    /// to access the response.
+    /// @param headers Headers to use for this request. Defaults to none.
+    /// @param max_redirects How many redirects to follow. Defaults to none.
     void options(std::string url, std::function<void(const Request &)> callback, const Headers &headers = {},
                  long max_redirects = 0);
+
+    /// @brief Make a simple PUT request with a body.
+    /// @param url The url to request.
+    /// @param request_body The body to use with this request.
+    /// @param mimetype The mimetype of the @a request_body.
+    /// @param callback The callback, which will be called after the request is
+    /// completed. The request will be passed as a parameter, which you can use
+    /// to access the response.
+    /// @param headers Headers to use for this request. Defaults to none.
+    /// @param max_redirects How many redirects to follow. Defaults to none.
     void put(std::string url, std::string request_body, std::string mimetype,
              std::function<void(const Request &)> callback, const Headers &headers = {}, long max_redirects = 0);
+
+    /// @brief Make a simple POST request with a body.
+    /// @param url The url to request.
+    /// @param request_body The body to use with this request.
+    /// @param mimetype The mimetype of the @a request_body.
+    /// @param callback The callback, which will be called after the request is
+    /// completed. The request will be passed as a parameter, which you can use
+    /// to access the response.
+    /// @param headers Headers to use for this request. Defaults to none.
+    /// @param max_redirects How many redirects to follow. Defaults to none.
     void post(std::string url, std::string request_body, std::string mimetype,
               std::function<void(const Request &)> callback, const Headers &headers = {}, long max_redirects = 0);
 
-    static void set_logger(std::shared_ptr<spdlog::logger> l) { log = std::move(l); }
+    /// @brief Set a global @a logger.
+    /// @param logger The spdlog logger to use for logging.
+    ///
+    /// Set the logger while no requests are in flight, for example before
+    /// starting the first request.
+    static void set_logger(std::shared_ptr<spdlog::logger> logger) { log = std::move(logger); }
+    //! Set whether to \a verify the https certificates or not.
     void set_verify_peer(bool verify) { this->verify_peer_ = verify; }
+    /// @brief Query whether certificate verification is enabled or not
+    /// @sa set_verify_peer
     bool does_verify_peer() { return this->verify_peer_; }
 
     //! Timeout connection after the specified amount of seconds, if the server

include/coeurl/headers.hpp

 #pragma once
 
+/// @file
+/// @brief Include for the @ref coeurl::Headers
+
 #include <map>
 #include <string>
 
 namespace coeurl {
+/// @brief custom comparator used in the headers map
+///
+/// Used for caseinsensitive comparisons
 struct header_less {
+    //! Comparison operator, returns true if the lhs is caseinsensitively less than
+    //! the rhs.
     bool operator()(const std::string &, const std::string &) const;
 };
 
+/// @brief A type to hold headers by name.
+///
+/// A map from a case insensitive header name to the header value.
 using Headers = std::map<std::string, std::string, header_less>;
 } // namespace coeurl

include/coeurl/request.hpp

 #pragma once
 
+/// @file
+/// @brief Include for the @ref coeurl::Request
+
 #include <functional>
 #include <string>
 
@@ -10,40 +13,71 @@
 namespace coeurl {
 struct Client;
 
+/// @brief A HTTP request.
+///
+/// Can be sent using a @ref Client
+/// You can listen to various events here and access the response, after it
+/// finished.
 struct Request {
+    //! The different HTTP methods.
     enum class Method {
-        Delete,
-        Get,
-        Head,
-        Options,
-        Patch,
-        Post,
-        Put,
+        Delete,  //!< HTTP DELETE
+        Get,     //!< HTTP GET
+        Head,    //!< HTTP HEAD
+        Options, //!< HTTP OPTIONS
+        Patch,   //!< HTTP PATCH
+        Post,    //!< HTTP POST
+        Put,     //!< HTTP PUT
     };
 
-    Request(Client *client, Method m, std::string url_);
+    /// @brief construct a new request to @a url.
+    /// @param url The URL to request.
+    /// @param client The client to use.
+    /// @param method The http method for this request. Usually GET.
+    Request(Client *client, Method method, std::string url);
+    //! Cleans up a request.
     ~Request();
+    //! Uncopyable
     Request(Request const &) = delete;
+    //! Uncopyable
     void operator=(Request const &) = delete;
+    //! Unmoveable
     Request(Request &&) = delete;
+    //! Unmoveable
     void operator=(Request &&) = delete;
 
+    //! The maximum number of redirects. Defaults to 0.
     Request &max_redirects(long amount);
+    //! Whether to verify the certificate of the peer. Defaults to whatever is
+    //! set on the client (usually true).
     Request &verify_peer(bool verify);
+    //! The actual request body. \a contenttype defaults to
+    //! "application/octet-stream".
     Request &request(std::string r, std::string contenttype = "application/octet-stream");
+    /// @brief Headers for this request.
+    /// @sa request_headers
     Request &request_headers(const Headers &h);
     //! Timeout connection after the specified amount of seconds, if the server
     //! stops sending acks.
     Request &connection_timeout(long t);
 
+    //! Optional completion handler.
     Request &on_complete(const std::function<void(const Request &)> handler);
+    //! Optional upload progress handler.
     Request &on_upload_progress(std::function<void(size_t progress, size_t total)> handler);
+    //! Optional download progress handler.
     Request &on_download_progess(std::function<void(size_t progress, size_t total)> handler);
 
+    //! The url for this request.
     std::string_view url() const { return url_; }
+    //! The response in this request.
     std::string_view response() const { return response_; }
+    //! The HTTP response code. 200 for success.
     int response_code() const;
+    //! The curl error code. CURLE_OK (0) on success.
     CURLcode error_code() const { return curl_error; }
+    /// @brief Headers for the response
+    /// @sa request_headers
     Headers response_headers() const { return response_headers_; }
 
   private: