Mercurial > irccd
changeset 86:39fe49d294c8
Docs: add lot of doxygen documentation, #453
line wrap: on
line diff
--- a/doc/doxygen/Doxyfile.in Mon Apr 04 22:34:41 2016 +0200 +++ b/doc/doxygen/Doxyfile.in Tue Apr 05 23:01:35 2016 +0200 @@ -43,7 +43,7 @@ # for a project that appears at the top of each page and should give viewer a # quick idea about the purpose of the project. Keep the description short. -PROJECT_BRIEF = +PROJECT_BRIEF = "IRC Client Daemon" # With the PROJECT_LOGO tag one can specify an logo or icon that is included in # the documentation. The maximum height of the logo should not exceed 55 pixels @@ -143,7 +143,7 @@ # will be relative from the directory where doxygen is started. # This tag requires that the tag FULL_PATH_NAMES is set to YES. -STRIP_FROM_PATH = @DOXYGEN_INPUT@ +STRIP_FROM_PATH = @DOXYGEN_INPUT@/lib # The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the # path mentioned in the documentation of a class, which tells the reader which @@ -742,9 +742,7 @@ # spaces. # Note: If this tag is empty the current directory is searched. -INPUT = @DOXYGEN_INPUT@/irccd \ - @DOXYGEN_INPUT@/irccdctl \ - @DOXYGEN_INPUT@/common +INPUT = @DOXYGEN_INPUT@/lib # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses @@ -764,7 +762,7 @@ # *.md, *.mm, *.dox, *.py, *.f90, *.f, *.for, *.tcl, *.vhd, *.vhdl, *.ucf, # *.qsf, *.as and *.js. -FILE_PATTERNS = +FILE_PATTERNS = *.h # The RECURSIVE tag can be used to specify whether or not subdirectories should # be searched for input files as well. @@ -779,7 +777,7 @@ # Note that relative paths are relative to the directory from which doxygen is # run. -EXCLUDE = +EXCLUDE = lib/irccd/server-private.h # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or # directories that are symbolic links (a Unix file system feature) are excluded
--- a/lib/irccd/alias.h Mon Apr 04 22:34:41 2016 +0200 +++ b/lib/irccd/alias.h Tue Apr 05 23:01:35 2016 +0200 @@ -19,6 +19,11 @@ #ifndef IRCCD_ALIAS_H #define IRCCD_ALIAS_H +/** + * @file alias.h + * @brief Create irccdctl aliases. + */ + #include <ostream> #include <string> #include <vector> @@ -74,6 +79,12 @@ */ const std::string &value() const noexcept; + /** + * Output the alias to the stream. + * + * @param out the output stream + * @return out + */ friend std::ostream &operator<<(std::ostream &out, const AliasArg &); };
--- a/lib/irccd/application.h Mon Apr 04 22:34:41 2016 +0200 +++ b/lib/irccd/application.h Tue Apr 05 23:01:35 2016 +0200 @@ -19,6 +19,11 @@ #ifndef IRCCD_APPLICATION_H #define IRCCD_APPLICATION_H +/** + * @file application.h + * @brief Base class for irccd and irccdctl. + */ + #include <cassert> #include <memory> #include <unordered_map> @@ -27,20 +32,44 @@ namespace irccd { +/** + * Map of commands. + */ using RemoteCommands = std::unordered_map<std::string, std::unique_ptr<RemoteCommand>>; +/** + * @brief Base class for creating irccd front ends. + */ class Application { protected: + /** + * Map of commands. + */ RemoteCommands m_commands; public: + /** + * Create the application and fill the commands with predefined commands. + */ Application(); + /** + * Access the remote commands. + * + * @return the commands + */ inline const RemoteCommands &commands() const noexcept { return m_commands; } + /** + * Add a new command. + * + * @pre command must not be null + * @pre the command must not exist + * @param command the command + */ inline void addCommand(std::unique_ptr<RemoteCommand> command) { assert(command);
--- a/lib/irccd/cmd-plugin-info.h Mon Apr 04 22:34:41 2016 +0200 +++ b/lib/irccd/cmd-plugin-info.h Tue Apr 05 23:01:35 2016 +0200 @@ -64,7 +64,7 @@ /** * @copydoc RemoteCommand::result */ - void result(Irccdctl &irccdctl, const json::Value &object) const override; + void result(Irccdctl &irccdctl, const json::Value &response) const override; }; } // !command
--- a/lib/irccd/cmd-plugin-list.h Mon Apr 04 22:34:41 2016 +0200 +++ b/lib/irccd/cmd-plugin-list.h Tue Apr 05 23:01:35 2016 +0200 @@ -54,7 +54,7 @@ /** * @copydoc RemoteCommand::result */ - void result(Irccdctl &irccdctl, const json::Value &object) const override; + void result(Irccdctl &irccdctl, const json::Value &response) const override; }; } // !command
--- a/lib/irccd/cmd-plugin-load.h Mon Apr 04 22:34:41 2016 +0200 +++ b/lib/irccd/cmd-plugin-load.h Tue Apr 05 23:01:35 2016 +0200 @@ -42,19 +42,19 @@ PluginLoad(); /** - * @copydoc TransportCommand::help + * @copydoc RemoteCommand::help */ std::string help() const override; /** - * @copydoc TransportCommand::args + * @copydoc RemoteCommand::args */ std::vector<Arg> args() const override; /** - * @copydoc TransportCommand::exec + * @copydoc RemoteCommand::exec */ - json::Value exec(Irccd &irccd, const json::Value &object) const override; + json::Value exec(Irccd &irccd, const json::Value &request) const override; }; } // !command
--- a/lib/irccd/cmd-plugin-reload.h Mon Apr 04 22:34:41 2016 +0200 +++ b/lib/irccd/cmd-plugin-reload.h Tue Apr 05 23:01:35 2016 +0200 @@ -42,19 +42,19 @@ PluginReload(); /** - * @copydoc TransportCommand::help + * @copydoc RemoteCommand::help */ std::string help() const override; /** - * @copydoc TransportCommand::args + * @copydoc RemoteCommand::args */ std::vector<Arg> args() const override; /** - * @copydoc TransportCommand::exec + * @copydoc RemoteCommand::exec */ - json::Value exec(Irccd &irccd, const json::Value &object) const override; + json::Value exec(Irccd &irccd, const json::Value &request) const override; }; } // !command
--- a/lib/irccd/cmd-plugin-unload.h Mon Apr 04 22:34:41 2016 +0200 +++ b/lib/irccd/cmd-plugin-unload.h Tue Apr 05 23:01:35 2016 +0200 @@ -42,19 +42,19 @@ PluginUnload(); /** - * @copydoc TransportCommand::help + * @copydoc RemoteCommand::help */ std::string help() const override; /** - * @copydoc TransportCommand::args + * @copydoc RemoteCommand::args */ std::vector<Arg> args() const override; /** * @copydoc RemoteCommand::exec */ - json::Value exec(Irccd &irccd, const json::Value &object) const override; + json::Value exec(Irccd &irccd, const json::Value &request) const override; }; } // !command
--- a/lib/irccd/cmd-server-cmode.h Mon Apr 04 22:34:41 2016 +0200 +++ b/lib/irccd/cmd-server-cmode.h Tue Apr 05 23:01:35 2016 +0200 @@ -47,14 +47,14 @@ std::string help() const override; /** - * @copydoc TransportCommand::args + * @copydoc RemoteCommand::args */ std::vector<Arg> args() const override; /** - * @copydoc TransportCommand::exec + * @copydoc RemoteCommand::exec */ - json::Value exec(Irccd &irccd, const json::Value &object) const override; + json::Value exec(Irccd &irccd, const json::Value &request) const override; }; } // !command
--- a/lib/irccd/cmd-server-cnotice.h Mon Apr 04 22:34:41 2016 +0200 +++ b/lib/irccd/cmd-server-cnotice.h Tue Apr 05 23:01:35 2016 +0200 @@ -56,12 +56,12 @@ std::string help() const override; /** - * @copydoc TransportCommand::args + * @copydoc RemoteCommand::args */ std::vector<Arg> args() const override; /** - * @copydoc TransportCommand::exec + * @copydoc RemoteCommand::exec */ json::Value exec(Irccd &irccd, const json::Value &request) const override; };
--- a/lib/irccd/cmd-server-connect.h Mon Apr 04 22:34:41 2016 +0200 +++ b/lib/irccd/cmd-server-connect.h Tue Apr 05 23:01:35 2016 +0200 @@ -47,17 +47,17 @@ std::string help() const override; /** - * @copydoc TransportCommand::options + * @copydoc RemoteCommand::options */ std::vector<Option> options() const override; /** - * @copydoc TransportCommand::args + * @copydoc RemoteCommand::args */ std::vector<Arg> args() const override; /** - * @copydoc TransportCommand::exec + * @copydoc RemoteCommand::exec */ json::Value exec(Irccd &irccd, const json::Value &request) const override; };
--- a/lib/irccd/cmd-server-disconnect.h Mon Apr 04 22:34:41 2016 +0200 +++ b/lib/irccd/cmd-server-disconnect.h Tue Apr 05 23:01:35 2016 +0200 @@ -46,12 +46,17 @@ */ std::string help() const override; + /** + * Get list of arguments required. + * + * @return the arguments required + */ std::vector<Arg> args() const override; /** - * @copydoc TransportCommand::exec + * @copydoc RemoteCommand::exec */ - json::Value exec(Irccd &irccd, const json::Value &object) const override; + json::Value exec(Irccd &irccd, const json::Value &request) const override; }; } // !command
--- a/lib/irccd/cmd-server-info.h Mon Apr 04 22:34:41 2016 +0200 +++ b/lib/irccd/cmd-server-info.h Tue Apr 05 23:01:35 2016 +0200 @@ -44,17 +44,23 @@ std::string help() const override; /** - * @copydoc TransportCommand::args + * @copydoc RemoteCommand::args */ std::vector<Arg> args() const override; + /** + * @copydoc RemoteCommand::request + */ json::Value request(Irccdctl &irccdctl, const RemoteCommandRequest &args) const override; /** - * @copydoc TransportCommand::exec + * @copydoc RemoteCommand::exec */ - json::Value exec(Irccd &irccd, const json::Value &object) const override; + json::Value exec(Irccd &irccd, const json::Value &request) const override; + /** + * @copydoc RemoteCommand::result + */ void result(Irccdctl &irccdctl, const json::Value &response) const override; };
--- a/lib/irccd/cmd-server-invite.h Mon Apr 04 22:34:41 2016 +0200 +++ b/lib/irccd/cmd-server-invite.h Tue Apr 05 23:01:35 2016 +0200 @@ -54,7 +54,7 @@ json::Value request(Irccdctl &irccdctl, const RemoteCommandRequest &args) const override; /** - * @copydoc TransportCommand::exec + * @copydoc RemoteCommand::exec */ json::Value exec(Irccd &irccd, const json::Value &request) const override;
--- a/lib/irccd/cmd-server-me.h Mon Apr 04 22:34:41 2016 +0200 +++ b/lib/irccd/cmd-server-me.h Tue Apr 05 23:01:35 2016 +0200 @@ -20,7 +20,7 @@ #define IRCCD_CMD_SERVER_ME_H /** - * @file command-server-me.h + * @file cmd-server-me.h * @brief Implementation of server-me transport command. */
--- a/lib/irccd/cmd-watch.h Mon Apr 04 22:34:41 2016 +0200 +++ b/lib/irccd/cmd-watch.h Tue Apr 05 23:01:35 2016 +0200 @@ -48,7 +48,7 @@ /** * @copydoc RemoteCommand::request */ - json::Value request(Irccdctl &ctl, const RemoteCommandRequest &request) const override; + json::Value request(Irccdctl &irccdctl, const RemoteCommandRequest &request) const override; }; } // !command
--- a/lib/irccd/command.h Mon Apr 04 22:34:41 2016 +0200 +++ b/lib/irccd/command.h Tue Apr 05 23:01:35 2016 +0200 @@ -19,6 +19,11 @@ #ifndef IRCCD_COMMAND_H #define IRCCD_COMMAND_H +/** + * @file command.h + * @brief Remote commands. + */ + #include <cassert> #include <map> #include <vector> @@ -37,7 +42,14 @@ */ class RemoteCommandRequest { public: + /** + * The options given by command line. + */ using Options = std::multimap<std::string, std::string>; + + /** + * Command line arguments in the same order. + */ using Args = std::vector<std::string>; private: @@ -142,6 +154,7 @@ * Get the given option by its id or defaultValue if not found. * * @param key the option id + * @param defaultValue the value replacement * @return the option */ inline std::string optionOr(const std::string &key, std::string defaultValue) const noexcept @@ -194,6 +207,15 @@ bool m_visible; public: + /** + * Create the remote command. + * + * @pre name must not be empty + * @pre category must not be empty + * @param name the command name (e.g. server-list) + * @param category the category (e.g. Server) + * @param visible true if the command should be visible without verbosity + */ inline RemoteCommand(std::string name, std::string category, bool visible = true) noexcept : m_name(std::move(name)) , m_category(std::move(category)) @@ -323,8 +345,8 @@ * * This default implementation just check for an error string and shows it if any. * - * @param irccdctl the irccdctl instane - * @param object the result + * @param irccdctl the irccdctl instan e + * @param response the JSON response */ virtual void result(Irccdctl &irccdctl, const json::Value &response) const; }; @@ -351,9 +373,11 @@ * @pre id must not be empty * @pre at least simpleKey or longKey must not be empty * @pre description must not be empty - * @param key the key the option key + * @param id the option id + * @param simpleKey the key the option key + * @param longKey the long option name + * @param arg the argument name if needed * @param description the description - * @param flags the optional flags */ inline Option(std::string id, std::string simpleKey,
--- a/lib/irccd/connection.h Mon Apr 04 22:34:41 2016 +0200 +++ b/lib/irccd/connection.h Tue Apr 05 23:01:35 2016 +0200 @@ -19,6 +19,11 @@ #ifndef IRCCD_CONNECTION_H #define IRCCD_CONNECTION_H +/** + * @file connection.h + * @brief Connection to irccd instance. + */ + #include <cassert> #include <stdexcept> @@ -37,6 +42,9 @@ */ class Connection { protected: + /** + * Timer to track elapsed time. + */ ElapsedTimer m_timer; /** @@ -92,7 +100,7 @@ virtual void connect(int timeout = 30000) = 0; /** - * Try to send the message in 30 seconds. The message must not end with \r\n\r\n, it is added automatically. + * Try to send the message in 30 seconds. The message must not end with \\r\\n\\r\\n, it is added automatically. * * @pre msg must not be empty * @param msg the message to send
--- a/lib/irccd/elapsed-timer.h Mon Apr 04 22:34:41 2016 +0200 +++ b/lib/irccd/elapsed-timer.h Tue Apr 05 23:01:35 2016 +0200 @@ -39,10 +39,9 @@ * milliseconds only. */ class ElapsedTimer { -public: +private: using TimePoint = std::chrono::time_point<std::chrono::high_resolution_clock>; -private: TimePoint m_last; bool m_paused{false}; unsigned m_elapsed{0};
--- a/lib/irccd/irccd.h Mon Apr 04 22:34:41 2016 +0200 +++ b/lib/irccd/irccd.h Tue Apr 05 23:01:35 2016 +0200 @@ -19,6 +19,11 @@ #ifndef IRCCD_H #define IRCCD_H +/** + * @file irccd.h + * @brief Base class for irccd front end. + */ + #include <atomic> #include <cassert> #include <condition_variable> @@ -74,13 +79,13 @@ */ class ServerEvent { public: - std::string server; - std::string origin; - std::string target; - std::string json; + std::string server; //!< the server + std::string origin; //!< the originator + std::string target; //!< the target + std::string json; //!< the JSON message #if defined(WITH_JS) - std::function<std::string (Plugin &)> name; - std::function<void (Plugin &)> exec; + std::function<std::string (Plugin &)> name; //!< the function to event name + std::function<void (Plugin &)> exec; //!< the plugin function to call #endif }; @@ -239,11 +244,13 @@ */ void post(Event ev) noexcept; - /* + /** * This function wraps post() to iterate over all plugins to call the function and to send to all * connected transport the event. + * + * @param ev the event */ - void postServerEvent(ServerEvent) noexcept; + void postServerEvent(ServerEvent ev) noexcept; /* * Identity management @@ -500,7 +507,7 @@ /** * Remove a new rule from the specified position. * - * @param rule the rule + * @pre position must be valid * @param position the position */ inline void removeRule(unsigned position)
--- a/lib/irccd/irccdctl.h Mon Apr 04 22:34:41 2016 +0200 +++ b/lib/irccd/irccdctl.h Tue Apr 05 23:01:35 2016 +0200 @@ -19,6 +19,11 @@ #ifndef IRCCD_IRCCDCTL_H #define IRCCD_IRCCDCTL_H +/** + * @file irccdctl.h + * @brief Base class for irccdctl front end. + */ + #include <cassert> #include <map> #include <memory> @@ -39,6 +44,9 @@ } // !ini +/** + * @brief Main irccdctl class. + */ class Irccdctl : public Application { private: /* Irccd's information */ @@ -103,6 +111,12 @@ return *m_connection; } + /** + * Run the irccdctl front end. + * + * @param argc the number of arguments + * @param argv the arguments + */ void run(int argc, char **argv); };
--- a/lib/irccd/js-directory.h Mon Apr 04 22:34:41 2016 +0200 +++ b/lib/irccd/js-directory.h Tue Apr 05 23:01:35 2016 +0200 @@ -19,10 +19,20 @@ #ifndef IRCCD_JS_DIRECTORY_H #define IRCCD_JS_DIRECTORY_H +/** + * @file js-directory.h + * @brief Irccd.Directory JavaScript API. + */ + #include "js.h" namespace irccd { +/** + * Load the module. + * + * @param ctx the context. + */ void loadJsDirectory(duk::ContextPtr ctx) noexcept; } // !irccd
--- a/lib/irccd/js-elapsed-timer.h Mon Apr 04 22:34:41 2016 +0200 +++ b/lib/irccd/js-elapsed-timer.h Tue Apr 05 23:01:35 2016 +0200 @@ -19,10 +19,20 @@ #ifndef IRCCD_JS_ELAPSED_TIMER_H #define IRCCD_JS_ELAPSED_TIMER_H +/** + * @file js-elapsed-timer.h + * @brief Irccd.ElapsedTimer JavaScript API. + */ + #include "js.h" namespace irccd { +/** + * Load the module. + * + * @param ctx the context. + */ void loadJsElapsedTimer(duk::ContextPtr ctx) noexcept; } // !irccd
--- a/lib/irccd/js-file.h Mon Apr 04 22:34:41 2016 +0200 +++ b/lib/irccd/js-file.h Tue Apr 05 23:01:35 2016 +0200 @@ -19,6 +19,11 @@ #ifndef IRCCD_JS_FILE_H #define IRCCD_JS_FILE_H +/** + * @file js-file.h + * @brief Irccd.File JavaScript API. + */ + #include <cassert> #include <cerrno> #include <cstdio> @@ -50,7 +55,7 @@ File(File &&) = delete; File &operator=(File &&) = delete; -protected: +private: std::string m_path; std::FILE *m_stream; std::function<void (std::FILE *)> m_destructor; @@ -78,6 +83,7 @@ * * @pre destructor must not be null * @param fp the file pointer + * @param destructor the function to close fp (e.g. std::fclose) */ inline File(std::FILE *fp, std::function<void (std::FILE *)> destructor) noexcept : m_stream(fp) @@ -129,9 +135,17 @@ namespace duk { +/** + * @brief JavaScript binding for File. + */ template <> class TypeTraits<File> { public: + /** + * Push the File prototype. + * + * @param ctx the context + */ static inline void prototype(ContextPtr ctx) { getGlobal<void>(ctx, "Irccd"); @@ -141,11 +155,21 @@ remove(ctx, -2); } + /** + * Get the File signature. + * + * @return File + */ static inline std::string name() { return "\xff""\xff""File"; } + /** + * Get the inheritance list. + * + * @return empty + */ static inline std::vector<std::string> inherits() { return {}; @@ -154,6 +178,11 @@ } // !duk +/** + * Load the module. + * + * @param ctx the context. + */ void loadJsFile(duk::ContextPtr ctx); } // !irccd
--- a/lib/irccd/js-irccd.h Mon Apr 04 22:34:41 2016 +0200 +++ b/lib/irccd/js-irccd.h Tue Apr 05 23:01:35 2016 +0200 @@ -19,6 +19,11 @@ #ifndef IRCCD_JS_IRCCD_H #define IRCCD_JS_IRCCD_H +/** + * @file js-irccd.h + * @brief Irccd.Irccd JavaScript API. + */ + #include <cerrno> #include <cstring> @@ -26,25 +31,42 @@ namespace irccd { +/** + * @brief Custom JavaScript exception for system error. + */ class SystemError { private: int m_errno; std::string m_message; public: + /** + * Create a system error from the current errno value. + */ SystemError(); + /** + * Create a system error with the given errno and message. + * + * @param e the errno number + * @param message the message + */ SystemError(int e, std::string message); + /** + * Raise the SystemError. + * + * @param ctx the context + */ void raise(duk::ContextPtr ctx) const; - - std::string name() const - { - return "SystemError"; - } }; -void loadJsIrccd(duk::Context &); +/** + * Load the module. + * + * @param ctx the context. + */ +void loadJsIrccd(duk::Context &ctx); } // !irccd
--- a/lib/irccd/js-logger.h Mon Apr 04 22:34:41 2016 +0200 +++ b/lib/irccd/js-logger.h Tue Apr 05 23:01:35 2016 +0200 @@ -19,10 +19,20 @@ #ifndef IRCCD_JS_LOGGER_H #define IRCCD_JS_LOGGER_H +/** + * @file js-logger.h + * @brief Irccd.Logger JavaScript API. + */ + #include "js.h" namespace irccd { +/** + * Load the module. + * + * @param ctx the context. + */ void loadJsLogger(duk::ContextPtr ctx); } // !irccd
--- a/lib/irccd/js-plugin.h Mon Apr 04 22:34:41 2016 +0200 +++ b/lib/irccd/js-plugin.h Tue Apr 05 23:01:35 2016 +0200 @@ -19,10 +19,20 @@ #ifndef IRCCD_JS_PLUGIN_H #define IRCCD_JS_PLUGIN_H +/** + * @file js-plugin.h + * @brief Irccd.Plugin JavaScript API. + */ + #include "js.h" namespace irccd { +/** + * Load the module. + * + * @param ctx the context. + */ void loadJsPlugin(duk::Context &ctx) noexcept; } // !irccd
--- a/lib/irccd/js-server.h Mon Apr 04 22:34:41 2016 +0200 +++ b/lib/irccd/js-server.h Tue Apr 05 23:01:35 2016 +0200 @@ -19,19 +19,30 @@ #ifndef IRCCD_JS_SERVER_H #define IRCCD_JS_SERVER_H +/** + * @file js-server.h + * @brief Irccd.Server JavaScript API. + */ + #include <irccd/server.h> #include "js.h" namespace irccd { -void loadJsServer(duk::ContextPtr ctx); - namespace duk { +/** + * @brief JavaScript binding for Server. + */ template <> class TypeTraits<irccd::Server> { public: + /** + * Push the Server prototype. + * + * @param ctx the context + */ static inline void prototype(ContextPtr ctx) { getGlobal<void>(ctx, "Irccd"); @@ -41,11 +52,21 @@ remove(ctx, -2); } + /** + * Get the Server signature. + * + * @return Server + */ static inline std::string name() { return "\xff""\xff""Server"; } + /** + * Get the inheritance list. + * + * @return empty + */ static inline std::vector<std::string> inherits() { return {}; @@ -54,6 +75,13 @@ } // !duk +/** + * Load the module. + * + * @param ctx the context. + */ +void loadJsServer(duk::ContextPtr ctx); + } // !irccd #endif // !IRCCD_JS_SERVER_H
--- a/lib/irccd/js-system.h Mon Apr 04 22:34:41 2016 +0200 +++ b/lib/irccd/js-system.h Tue Apr 05 23:01:35 2016 +0200 @@ -19,10 +19,20 @@ #ifndef IRCCD_JS_SYSTEM_H #define IRCCD_JS_SYSTEM_H +/** + * @file js-system.h + * @brief Irccd.System JavaScript API. + */ + #include "js.h" namespace irccd { +/** + * Load the module. + * + * @param ctx the context. + */ void loadJsSystem(duk::ContextPtr ctx); } // !irccd
--- a/lib/irccd/js-timer.h Mon Apr 04 22:34:41 2016 +0200 +++ b/lib/irccd/js-timer.h Tue Apr 05 23:01:35 2016 +0200 @@ -19,10 +19,20 @@ #ifndef IRCCD_JS_TIMER_H #define IRCCD_JS_TIMER_H +/** + * @file js-timer.h + * @brief Irccd.Timer JavaScript API. + */ + #include "js.h" namespace irccd { +/** + * Load the module. + * + * @param ctx the context. + */ void loadJsTimer(duk::ContextPtr ctx) noexcept; } // !irccd
--- a/lib/irccd/js-unicode.h Mon Apr 04 22:34:41 2016 +0200 +++ b/lib/irccd/js-unicode.h Tue Apr 05 23:01:35 2016 +0200 @@ -19,10 +19,20 @@ #ifndef IRCCD_JS_UNICODE_H #define IRCCD_JS_UNICODE_H +/** + * @file js-unicode.h + * @brief Irccd.Unicode JavaScript API. + */ + #include "js.h" namespace irccd { +/** + * Load the module. + * + * @param ctx the context. + */ void loadJsUnicode(duk::ContextPtr ctx); } // !irccd
--- a/lib/irccd/js-util.h Mon Apr 04 22:34:41 2016 +0200 +++ b/lib/irccd/js-util.h Tue Apr 05 23:01:35 2016 +0200 @@ -19,10 +19,20 @@ #ifndef IRCCD_JS_UTIL_H #define IRCCD_JS_UTIL_H +/** + * @file js-util.h + * @brief Irccd.Util JavaScript API. + */ + #include "js.h" namespace irccd { +/** + * Load the module. + * + * @param ctx the context. + */ void loadJsUtil(duk::ContextPtr ctx); } // !irccd
--- a/lib/irccd/logger.h Mon Apr 04 22:34:41 2016 +0200 +++ b/lib/irccd/logger.h Tue Apr 05 23:01:35 2016 +0200 @@ -19,6 +19,11 @@ #ifndef IRCCD_LOGGER_H #define IRCCD_LOGGER_H +/** + * @file logger.h + * @brief Logging facilities. + */ + #include <irccd/sysconfig.h> #include <memory>
--- a/lib/irccd/options.h Mon Apr 04 22:34:41 2016 +0200 +++ b/lib/irccd/options.h Tue Apr 05 23:01:35 2016 +0200 @@ -19,6 +19,11 @@ #ifndef IRCCD_OPTION_PARSER_H #define IRCCD_OPTION_PARSER_H +/** + * @file options.h + * @brief Basic options parsing. + */ + #include <exception> #include <map> #include <string>
--- a/lib/irccd/path.h Mon Apr 04 22:34:41 2016 +0200 +++ b/lib/irccd/path.h Tue Apr 05 23:01:35 2016 +0200 @@ -19,6 +19,11 @@ #ifndef IRCCD_PATH_H #define IRCCD_PATH_H +/** + * @file path.h + * @brief Path management. + */ + #include <string> #include <vector>
--- a/lib/irccd/plugin.h Mon Apr 04 22:34:41 2016 +0200 +++ b/lib/irccd/plugin.h Tue Apr 05 23:01:35 2016 +0200 @@ -20,7 +20,7 @@ #define IRCCD_PLUGIN_H /** - * @file Plugin.h + * @file plugin.h * @brief Irccd plugins */ @@ -347,10 +347,19 @@ namespace duk { +/** + * @brief Push plugin information. + */ template <> class TypeTraits<irccd::PluginInfo> { public: - static void push(ContextPtr ctx, const irccd::PluginInfo &info); + /** + * Push the plugin information as JavaScript object. + * + * @param ctx the context + * @param info the plugin information + */ + static void push(ContextPtr ctx, const PluginInfo &info); }; } // !duk
--- a/lib/irccd/server-private.h Mon Apr 04 22:34:41 2016 +0200 +++ b/lib/irccd/server-private.h Tue Apr 05 23:01:35 2016 +0200 @@ -32,27 +32,44 @@ */ class Server::Session { public: + /** + * libircclient handle. + */ using Handle = std::unique_ptr<irc_session_t, void (*)(irc_session_t *)>; private: Handle m_handle; public: + /** + * Create a null session. + */ inline Session() : m_handle(nullptr, nullptr) { } + /** + * Convert the libircclient session. + */ inline operator const irc_session_t *() const noexcept { return m_handle.get(); } + /** + * Overloaded function. + */ inline operator irc_session_t *() noexcept { return m_handle.get(); } + /** + * Get the handle. + * + * @return the handle + */ inline Handle &handle() noexcept { return m_handle;
--- a/lib/irccd/server-state.h Mon Apr 04 22:34:41 2016 +0200 +++ b/lib/irccd/server-state.h Tue Apr 05 23:01:35 2016 +0200 @@ -19,6 +19,11 @@ #ifndef IRCCD_SERVER_STATE_H #define IRCCD_SERVER_STATE_H +/** + * @file server-state.h + * @brief Server state. + */ + #include <irccd/sysconfig.h> #include "elapsed-timer.h" @@ -61,10 +66,29 @@ void prepareDisconnected(Server &, fd_set &setinput, fd_set &setoutput, net::Handle &maxfd); public: + /** + * Create the server state. + * + * @pre type must be valid + * @param type the type + */ ServerState(Type type); + /** + * Prepare the state. + * + * @param server the server + * @param setinput the read set + * @param setoutput the write set + * @param maxfd the maximum fd + */ void prepare(Server &server, fd_set &setinput, fd_set &setoutput, net::Handle &maxfd); + /** + * Get the state type. + * + * @return the type + */ inline Type type() const noexcept { return m_type;
--- a/lib/irccd/server.h Mon Apr 04 22:34:41 2016 +0200 +++ b/lib/irccd/server.h Tue Apr 05 23:01:35 2016 +0200 @@ -19,6 +19,11 @@ #ifndef IRCCD_SERVER_H #define IRCCD_SERVER_H +/** + * @file server.h + * @brief IRC Server. + */ + #include <cstdint> #include <functional> #include <map> @@ -365,7 +370,7 @@ */ Signal<std::string, std::string, std::string> onTopic; - /* + /** * Signal: onWhois * ------------------------------------------------ * @@ -732,7 +737,7 @@ * message terminators. * * @warning Use this function with care - * @param raw the raw message (without \r\n\r\n) + * @param raw the raw message (without `\r\n\r\n`) * @note Thread-safe */ void send(std::string raw);
--- a/lib/irccd/transport-client.h Mon Apr 04 22:34:41 2016 +0200 +++ b/lib/irccd/transport-client.h Tue Apr 05 23:01:35 2016 +0200 @@ -137,7 +137,6 @@ }; /** - * @class TransportClient * @brief Template class for Tcp and Ssl sockets */ template <typename Address> @@ -153,7 +152,7 @@ /** * Create a client. * - * @param sock the socket + * @param socket the socket */ inline TransportClientBase(net::SocketTcp<Address> socket) : m_socket(std::move(socket))
--- a/lib/irccd/util.h Mon Apr 04 22:34:41 2016 +0200 +++ b/lib/irccd/util.h Tue Apr 05 23:01:35 2016 +0200 @@ -19,6 +19,11 @@ #ifndef IRCCD_UTIL_H #define IRCCD_UTIL_H +/** + * @file util.h + * @brief Utilities. + */ + #include <ctime> #include <initializer_list> #include <regex> @@ -70,52 +75,47 @@ /** * Format a string and update all templates. * - * Syntax - * ====== + * ## Syntax * - * The syntax is ?{} where ? is replaced by one of the token defined below. Braces are mandatory and cannot be ommited. + * The syntax is <strong>?{}</strong> where <strong>?</strong> is replaced by one of the token defined below. Braces + * are mandatory and cannot be ommited. + * * To write a literal template construct, prepend the token twice. * - * Availables templates - * ==================== + * ## Availables templates * * The following templates are available: * - * - #{name}, name will be substituted from the keywords in params - * - ${name}, name will be substituted from the environment variable - * - @{attributes}, the attributes will be substituted to IRC colors (see below) - * - %, any format accepted by strftime(3) + * - <strong>\#{name}</strong>: name will be substituted from the keywords in params, + * - <strong>\${name}</strong>: name will be substituted from the environment variable, + * - <strong>\@{attributes}</strong>: the attributes will be substituted to IRC colors (see below), + * - <strong>%</strong>, any format accepted by strftime(3). * - * Attributes - * ========== + * ## Attributes * * The attribute format is composed of three parts, foreground, background and modifiers, each separated by a comma. * * **Note:** you cannot omit parameters, to specify the background, you must specify the foreground. * - * Examples - * ======== + * ## Examples * - * Valid constructs - * ---------------- + * ### Valid constructs * - * - `#{target}, welcome`: if target is set to "irccd", becomes "irccd, welcome", - * - `@{red}#{target}`: if target is specified, it is written in red, + * - <strong>\#{target}, welcome</strong>: if target is set to "irccd", becomes "irccd, welcome", + * - <strong>\@{red}\#{target}</strong>: if target is specified, it is written in red, * - * Invalid or literals constructs - * ------------------------------ + * ### Invalid or literals constructs * - * - `##{target}`: will output "#{target}", - * - `##`: will output "##", - * - `#target`: will output "#target", - * - `#{target`: will throw std::invalid_argument. + * - <strong>\#\#{target}</strong>: will output "\#{target}", + * - <strong>\#\#</strong>: will output "\#\#", + * - <strong>\#target</strong>: will output "\#target", + * - <strong>\#{target</strong>: will throw std::invalid_argument. * - * Colors & attributes - * ------------------- + * ### Colors & attributes * - * - `@{red,blue}`: will write text red on blue background, - * - `@{default,yellow}`: will write default color text on yellow background - * - `@{white,black,bold,underline}`: will write white text on black in both bold and underline + * - <strong>\@{red,blue}</strong>: will write text red on blue background, + * - <strong>\@{default,yellow}</strong>: will write default color text on yellow background, + * - <strong>\@{white,black,bold,underline}</strong>: will write white text on black in both bold and underline. */ std::string format(std::string text, const Substitution ¶ms = {}); @@ -131,7 +131,7 @@ * Split a string by delimiters. * * @param list the string to split - * @param delimiter a list of delimiters + * @param delimiters a list of delimiters * @param max max number of split * @return a list of string splitted */