From 1d3275e429a58a6e1949d13ddb32433dc2724526 Mon Sep 17 00:00:00 2001
From: tastytea <tastytea@tastytea.de>
Date: Fri, 3 Jan 2020 10:59:04 +0100
Subject: [PATCH] Add documentation.

---
 Doxyfile                 | 27 +++++++++++++++++++++++
 build_doc.sh             | 11 ++++++++++
 include/mastodonpp.hpp   | 47 ++++++++++++++++++++++++++++++++++++++++
 include/return_types.hpp | 47 ++++++++++++++++++++++++++++++++++++++++
 4 files changed, 132 insertions(+)
 create mode 100644 Doxyfile
 create mode 100755 build_doc.sh

diff --git a/Doxyfile b/Doxyfile
new file mode 100644
index 0000000..5484c91
--- /dev/null
+++ b/Doxyfile
@@ -0,0 +1,27 @@
+# -*- mode: conf-unix -*-
+INPUT                  = src/ include/
+RECURSIVE              = YES
+STRIP_FROM_INC_PATH    = "include"
+EXAMPLE_PATH           = examples/
+EXAMPLE_RECURSIVE      = YES
+GENERATE_HTML          = YES
+HTML_OUTPUT            = doc/html
+GENERATE_LATEX         = NO
+ALLOW_UNICODE_NAMES    = YES
+BRIEF_MEMBER_DESC      = YES
+REPEAT_BRIEF           = YES
+ALWAYS_DETAILED_SEC    = YES
+INLINE_INHERITED_MEMB  = NO
+INHERIT_DOCS           = YES
+SEPARATE_MEMBER_PAGES  = NO
+TAB_SIZE               = 4
+MARKDOWN_SUPPORT       = YES
+AUTOLINK_SUPPORT       = YES
+INLINE_SIMPLE_STRUCTS  = NO
+QUIET                  = NO
+WARNINGS               = YES
+BUILTIN_STL_SUPPORT    = YES
+VERBATIM_HEADERS       = YES
+INLINE_SOURCES         = YES
+SEARCHENGINE           = YES
+SHOW_FILES             = YES
diff --git a/build_doc.sh b/build_doc.sh
new file mode 100755
index 0000000..40b1371
--- /dev/null
+++ b/build_doc.sh
@@ -0,0 +1,11 @@
+#!/bin/sh
+
+project="$(realpath --relative-base=.. .)"
+version="$(grep -Eo '[0-9]+.[0-9]+.[0-9]+$' CMakeLists.txt)"
+
+if [[ -f Doxyfile ]]; then
+    mkdir -p doc
+    (doxygen -s -g - && cat Doxyfile &&
+         echo "PROJECT_NAME = ${project}" &&
+         echo "PROJECT_NUMBER = ${version}") | doxygen -
+fi
diff --git a/include/mastodonpp.hpp b/include/mastodonpp.hpp
index 606e61a..080d4b2 100644
--- a/include/mastodonpp.hpp
+++ b/include/mastodonpp.hpp
@@ -20,14 +20,61 @@
 #include "return_types.hpp"
 #include <string>
 
+/*!
+ *  @mainpage mastodonpp Reference
+ *
+ *  @section using Using the library
+ *
+ *  Include mastodonpp.hpp, which then includes all other headers.
+ *
+ *  @code
+ *  #include <mastodonpp/mastodonpp.hpp>
+ *  @endcode
+ *
+ *  Use it in your CMake project like this:
+ *
+ *  @code
+ *  find_package(mastodonpp REQUIRED CONFIG)
+ *  target_link_libraries(MyProject mastodonpp::mastodonpp)
+ *  @endcode
+ *
+ *  Or compile your code with `g++ $(pkg-config --cflags --libs mastodonpp)`.
+ *
+ *  @section Example
+ *
+ *  @code
+ *  mastodonpp::API masto("example.com", "");
+ *  @endcode
+ */
+
 namespace mastodonpp
 {
 
 using std::string;
 
+/*!
+ *  @brief  C++ wrapper for the Mastodon API.
+ *
+ *  All text input is expected to be UTF-8.
+ *
+ *  @since  0.1.0
+ *
+ */
+
 class API
 {
 public:
+    /*!
+     *  @brief  Construct a new API object.
+     *
+     *  To register your application, leave access_token blank and call
+     *  API::register_app1() and API::register_app2().
+     *
+     *  @param  instance     The hostname of your instance.
+     *  @param  access_token Your access token.
+     *
+     *  @since  0.1.0
+     */
     explicit API(string instance, string access_token);
 
 private:
diff --git a/include/return_types.hpp b/include/return_types.hpp
index e9d7db8..7d09519 100644
--- a/include/return_types.hpp
+++ b/include/return_types.hpp
@@ -29,15 +29,62 @@ using std::uint16_t;
 using std::string;
 using std::string_view;
 
+/*!
+ *  @brief  Return type for API calls.
+ *
+ *  @since  0.1.0
+ *
+ *  @section error Error codes
+ *  |      Code | Explanation                                                  |
+ *  | --------: |:-------------------------------------------------------------|
+ *  |         0 | No error.                                                    |
+ */
 struct answer
 {
+    /*!
+     *  @brief  @ref error "Error code".
+     *
+     *  @since  0.1.0
+     */
     uint8_t error_code;
+    /*!
+     *  @brief  The error message.
+     *
+     *  @since  0.1.0
+     */
     string error_message;
+    /*!
+     *  @brief  HTTP status code.
+     *
+     *  @since  0.1.0
+     */
     uint16_t http_status;
+    /*!
+     *  @brief  The response from the server, usually JSON.
+     *
+     *  @since  0.1.0
+     */
     string body;
 
+    /*!
+     *  @brief  Returns true if answer::error_code is 0, false otherwise.
+     *
+     *  @since  0.1.0
+     */
     explicit operator bool() const;
+
+    /*!
+     *  @brief  Returns answer::body as std::string_view.
+     *
+     *  @since  0.1.0
+     */
     explicit operator string_view() const;
+
+    /*!
+     *  @brief  Returns answer::body as std::ostream.
+     *
+     *  @since  0.1.0
+     */
     friend std::ostream &operator <<(std::ostream &out, const answer &answer);
 };