Merge branch 'develop' into main

.gitignore

@@ -1,2 +1,4 @@
 /build/
 /doc/
+/update_doc.sh
+/examples/example99*

CMakeLists.txt

@@ -20,7 +20,7 @@ list(APPEND CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/cmake")
 # Project build options.
 option(WITH_TESTS "Compile tests." NO)
 # option(WITH_DOC "Generate HTML documentation." YES)
-# option(WITH_EXAMPLES "Compile examples." NO)
+option(WITH_EXAMPLES "Compile examples." NO)
 # option(WITH_DEB "Prepare for the building of .deb packages." NO)
 # option(WITH_RPM "Prepare for the building of .rpm packages." NO)
 
@@ -36,4 +36,8 @@ if(WITH_TESTS)
   add_subdirectory(tests)
 endif()
 
+if(WITH_EXAMPLES)
+  add_subdirectory(examples)
+endif()
+
 # include(cmake/packages.cmake)

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

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

examples/CMakeLists.txt

@@ -0,0 +1,13 @@
+include(GNUInstallDirs)
+
+file(GLOB sources_examples *.cpp)
+foreach(src ${sources_examples})
+  get_filename_component(bin ${src} NAME_WE)
+  add_executable(${bin} ${src})
+  target_link_libraries(${bin} PRIVATE ${PROJECT_NAME})
+endforeach()
+
+if(WITH_DOC)
+  install(FILES ${sources_examples}
+    DESTINATION "${CMAKE_INSTALL_DOCDIR}/${PROJECT_NAME}/examples")
+endif()

include/mastodonpp.hpp

@@ -17,16 +17,64 @@
 #ifndef MASTODONPP_HPP
 #define MASTODONPP_HPP
 
+#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:

include/return_types.hpp

@@ -0,0 +1,93 @@
+/*  This file is part of mastodonpp.
+ *  Copyright © 2020 tastytea <tastytea@tastytea.de>
+ *
+ *  This program is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU Affero General Public License as published by
+ *  the Free Software Foundation, version 3.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU Affero General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Affero General Public License
+ *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#ifndef MASTODONPP_RETURN_TYPES_HPP
+#define MASTODONPP_RETURN_TYPES_HPP
+
+#include <cstdint>
+#include <string>
+#include <string_view>
+
+namespace mastodonpp
+{
+
+using std::uint8_t;
+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);
+};
+
+} // namespace mastodonpp
+
+#endif  // MASTODONPP_RETURN_TYPES_HPP

src/return_types.cpp

@@ -0,0 +1,38 @@
+/*  This file is part of mastodonpp.
+ *  Copyright © 2020 tastytea <tastytea@tastytea.de>
+ *
+ *  This program is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU Affero General Public License as published by
+ *  the Free Software Foundation, version 3.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU Affero General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Affero General Public License
+ *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#include "return_types.hpp"
+
+namespace mastodonpp
+{
+
+answer::operator bool() const
+{
+    return (error_code == 0);
+}
+
+answer::operator string_view() const
+{
+    return body;
+}
+
+std::ostream &operator <<(std::ostream &out, const answer &answer)
+{
+    out << answer.body;
+    return out;
+}
+
+} // namespace mastodonpp