add all public-facing docs

Author: TheMoonThatRises

.gitignore

@@ -1,2 +1,3 @@
 build/
 .vscode/
+docs/

Doxyfile

@@ -1,3 +1,88 @@
 # Discord IPC CPP
 
-C++ library for interfacing with Discord IPC socket.
+C++ library for interfacing with Discord IPC socket. This library was initial made for the parent project [apple-music-rpc-cpp](https://github.com/TheMoonThatRises/apple-music-rpc-cpp), and thus may not be contain full compatibility with Discord IPC protocols. Because of the criteria for the parent project, this library is entirely self-contained, and does not include any external libraries. Feel free to create a [new issue](https://github.com/TheMoonThatRises/discord_ipc_cpp/issues/new) or submit [pull requests](https://github.com/TheMoonThatRises/discord_ipc_cpp/pulls) if you encounter any issues.
+
+## Documentation
+
+Read the full documentation here: [https://plduanm.com/projects/documentation/discord_ipc_cpp](https://plduanm.com/projects/documentation/discord_ipc_cpp)
+
+## Installation
+
+Requirements:
+
+- A Unix system
+- CMake >= 3.14
+- C++ >= 20
+
+Clone this repository as a submodule under `src/`:
+
+```bash
+git submodule add https://github.com/TheMoonThatRises/discord_ipc_cpp src/discord_ipc_cpp
+```
+
+And add the following into your `CMakeLists.txt`:
+
+```cmake
+...
+
+add_subdirectory(src/discord_ipc_cpp)
+
+...
+
+target_link_libraries(<EXECUTABLE> PRIVATE discord_ipc_cpp)
+```
+
+## Basic Usage
+
+All of the code below will incorporate the following metacode:
+
+```c++
+#include <discord_ipc_cpp/discord_ipc_client.hpp>
+#include <discord_ipc_cpp/ipc_types.hpp>
+
+using discord_ipc_cpp::DiscordIPCClient;
+
+using discord_ipc_cpp::ipc_types::RichPresence;
+```
+
+Create a Discord IPC client and connect to it:
+
+```c++
+DiscordIPCClient client("<APPLICATION ID>");
+
+// indicates success of connecting to socket
+bool ret = client.connect();
+```
+
+Construct a rich presence:
+
+```c++
+RichPresence presence = {
+  .name = "Apple Music",
+  .type = RichPresence::at_listening,
+  .status_display_type = RichPresence::sdt_details,
+  .assets = {
+    .large_text = "Kawakiwoameku - EP"
+  },
+  .details = "Hollowness",
+  .state = "Minami"
+}
+```
+
+Set the user's rich presence:
+
+```c++
+client.set_presence(presence);
+```
+
+Clear the user's rich presence:
+
+```c++
+client.set_empty_presence();
+```
+
+Close the IPC connection:
+
+```c++
+client.close();
+```

README.md

@@ -17,40 +17,223 @@
 #include "discord_ipc_cpp/ipc_types.hpp"
 #include "discord_ipc_cpp/json.hpp"
 
+/**
+ * \namespace discord_ipc_cpp
+ *
+ * \brief High level namespace for the \c discord_ipc_cpp package.
+ *
+ * Contains all the necessary classes to interact with Discord's IPC socket,
+ * with other helpful classes neatly categorized.
+ */
 namespace discord_ipc_cpp {
+/**
+ * \brief Represents a connection to Discord's IPC socket.
+ *
+ * This class is the highest level and least-customizable class used to interact
+ * with Discord's IPC socket. It is specially designed to handle connections
+ * with the purpose of sending rich presence updates.
+ *
+ * \see discord_ipc_cpp::websockets::SocketClient
+ */
 class DiscordIPCClient {
  private:
+  /**
+   * \brief Stores the executable's process ID.
+   *
+   * Each rich presence is required to have an attached process ID to
+   * distinguish between different applications.
+   */
   const pid_t _pid;
+  /**
+   * \brief ID of the application.
+   *
+   * This points to the Discord application that the rich presence is sent from.
+   */
   std::string _client_id;
 
+  /**
+   * \brief Underlying socket connection.
+   *
+   * This is the actual class that handles connections to Discord's IPC socket.
+   *
+   * \see discord_ipc_cpp::websockets::SocketClient
+   */
   websockets::SocketClient _socket;
+  /**
+   * \brief Handles incoming packets.
+   *
+   * This thread handles incoming packets sent by Discord through the IPC
+   * socket.
+   *
+   * \see recv_thread
+   */
   std::thread _socket_recv_thread;
 
+  /**
+   * \brief Controls the state of \ref _socket_recv_thread.
+   *
+   * When this variable is toggled from \c false to \c true,
+   * \ref _socket_recv_thread will receive the notice to terminate the \c while
+   * loop.
+   *
+   * \see recv_thread()
+   */
   std::atomic_bool _stop_recv_thread;
+  /**
+   * \brief Indicates successful authentication with Discord socket.
+   *
+   * This variable ensures that packets are only sent after successful
+   * authentication with Discord's IPC socket. Otherwise, each \ref send_packet
+   * request will automatically return \c false.
+   */
   std::atomic_bool _successful_auth;
 
  private:
+  /**
+   * \brief Encodes payload into byte buffer.
+   *
+   * Takes an input \p payload and converts it into the formatted byte buffer
+   * with the proper size that the Discord IPC socket expects.
+   *
+   * \param payload Data payload to encode.
+   *
+   * \return The \p payload converted into a byte buffer.
+   */
   static std::vector<char> encode_packet(const ipc_types::Payload& payload);
+  /**
+   * \brief Receives and handles incoming packets.
+   *
+   * This function is wrapped by the thread \ref _socket_recv_thread to receive
+   * incoming packets from the socket, ensuring the main thread is not blocked.
+   * The longevity of the function is controlled by the variable
+   * \ref _stop_recv_thread, which is the boolean checker within the \c while
+   * statement.
+   */
   void recv_thread();
 
  protected:
+ /**
+  * \brief Sends packet to socket.
+  *
+  * Attempts to send a payload packet to the Discord IPC socket and indicates
+  * the success. This function is a wrapper for
+  * \ref discord_ipc_cpp::websockets::SocketClient::send_data, as it takes an
+  * input \p payload and encodes it first with \ref encode_packet before calling
+  * the underlying method.
+  *
+  * \param payload Payload to send.
+  *
+  * \return Success of sending the packet.
+  *
+  * \see discord_ipc_cpp::websockets::SocketClient::send_data
+  */
   bool send_packet(const ipc_types::Payload& payload);
+  /**
+   * \brief Receive packet from socket.
+   *
+   * Attempts to receive a packet from the socket using
+   * \ref discord_ipc_cpp::websockets::SocketClient::recv_data(int,int) before
+   * retrieving the rest of packet with
+   * \ref discord_ipc_cpp::websockets::SocketClient::recv_data(int). The initial
+   * attempt to retrieve a packet contains a timeout, after which it returns an
+   * empty value.
+   *
+   * \return An optional payload.
+   *
+   * \see discord_ipc_cpp::websockets::SocketClient::recv_data(int)
+   * \see discord_ipc_cpp::websockets::SocketClient::recv_data(int,int)
+   */
   std::optional<ipc_types::Payload> recv_packet();
 
+  /**
+   * \brief Constructs a presence payload.
+   *
+   * The converts an optional input \p presence into a payload that can be sent
+   * to the socket.
+   *
+   * \param presence Presence to set into a payload.
+   *
+   * \return Payload with the corresponding \p presence.
+   */
   ipc_types::Payload construct_presence_payload(
     const std::optional<ipc_types::RichPresence>& presence);
 
+  /**
+   * \brief Attempts to send a payload.
+   *
+   * Wrapping around the method \ref send_packet, this method attempts to send
+   * the \p payload \p max_retry_count times with a delay of one second between
+   * each attempt.
+   *
+   * \param payload Payload to attempt sending.
+   * \param max_retry_count Maximum number of times to attempt sending payload.
+   *
+   * \return Success of the attempt to send \p payload.
+   */
   bool attempt_send_payload(
     const ipc_types::Payload& payload, int max_retry_count);
 
  public:
+  /**
+   * \brief Constructs the IPC client.
+   *
+   * Creates the IPC client with the \p client_id to be used when sending
+   * rich presences.
+   */
   explicit DiscordIPCClient(const std::string& client_id);
+  /**
+   * \brief Deallocates IPC client.
+   *
+   * Cleans up the IPC client by releasing the underlying socket connection.
+   *
+   * \see close
+   */
   ~DiscordIPCClient();
 
+  /**
+   * \brief Connect to IPC socket.
+   *
+   * Attempts to connect to IPC socket and authorize the application. After
+   * proper authorization, \ref _socket_recv_thread will be set and the
+   * application will start listening for incoming packets.
+   *
+   * \return Success of the attempt to connect.
+   *
+   * \see discord_ipc_cpp::websockets::SocketClient::connect
+   */
   bool connect();
+  /**
+   * \brief Close connection to IPC socket.
+   *
+   * Attempts to close the connection with the IPC socket by first sending a
+   * closure Op code and then signalling for \ref _socket_recv_thread to stop by
+   * setting \ref _stop_recv_thread to \c false. Lastly, the underlying socket
+   * is closed.
+   *
+   * \return Success of the attempt to close connection.
+   *
+   * \see discord_ipc_cpp::websockets::SocketClient::close
+   */
   bool close();
 
+  /**
+   * \brief Sets the presence in Discord.
+   *
+   * Sends a request to set the presence of the connected Discord user with
+   * \p presence.
+   *
+   * \param presence Presence to set.
+   *
+   * \return Success of setting the presence.
+   */
   bool set_presence(const ipc_types::RichPresence& presence);
+  /**
+   * \brief Sets an empty presence in Discord.
+   *
+   * Sends a request to set an empty presence.
+   *
+   * \return Success fo setting an empty presence.
+   */
   bool set_empty_presence();
 };
 }  // namespace discord_ipc_cpp