Mercurial > irccd
changeset 798:952021a03ace
doc: more doxygen improvements
author | David Demelier <markand@malikania.fr> |
---|---|
date | Mon, 12 Nov 2018 13:19:28 +0100 |
parents | 2dfba38e93f0 |
children | f362994133ca |
files | libirccd-core/irccd/acceptor.hpp libirccd-core/irccd/connector.hpp libirccd-core/irccd/stream.hpp libirccd/irccd/daemon/command.hpp libirccd/irccd/daemon/irccd.hpp libirccd/irccd/daemon/logger.hpp libirccd/irccd/daemon/plugin.hpp libirccd/irccd/daemon/plugin_service.hpp libirccd/irccd/daemon/rule.hpp libirccd/irccd/daemon/rule_service.hpp libirccd/irccd/daemon/server.hpp libirccd/irccd/daemon/server_service.hpp libirccd/irccd/daemon/transport_client.hpp libirccd/irccd/daemon/transport_server.hpp libirccd/irccd/daemon/transport_service.hpp |
diffstat | 15 files changed, 213 insertions(+), 24 deletions(-) [+] |
line wrap: on
line diff
--- a/libirccd-core/irccd/acceptor.hpp Sun Nov 11 15:44:20 2018 +0100 +++ b/libirccd-core/irccd/acceptor.hpp Mon Nov 12 13:19:28 2018 +0100 @@ -24,6 +24,12 @@ * \brief Abstract stream acceptor interface. */ +/** + * \defgroup acceptors Generic I/O acceptors + * \ingroup networking + * \brief Generic I/O acceptors. + */ + #include <irccd/sysconfig.hpp> #include <cassert> @@ -44,6 +50,7 @@ /** * \brief Abstract stream acceptor interface. + * \ingroup acceptors * * This class is used to wait a new client in an asynchronous manner. Derived * classes must implement a non-blocking accept function. @@ -83,6 +90,7 @@ /** * \brief Convenient acceptor owner. + * \ingroup acceptors */ template <typename Acceptor> class basic_socket_acceptor : public acceptor { @@ -230,6 +238,7 @@ /** * \brief TCP/IP acceptor. + * \ingroup acceptors */ class ip_acceptor : public basic_socket_acceptor<boost::asio::ip::tcp::acceptor> { private: @@ -239,6 +248,13 @@ public: /** + * Construct a TCP/IP acceptor. + * + * If both ipv4 and ipv6 are set, the acceptor will listen on the two + * protocols. + * + * To listen to any address, you can use "*" as address argument. + * * \pre at least ipv4 or ipv6 must be true * \param service the I/O service * \param address the address to bind or * for any @@ -340,6 +356,7 @@ /** * \brief Local acceptor. + * \ingroup acceptors * \note Only available if BOOST_ASIO_HAS_LOCAL_SOCKETS is defined */ class local_acceptor : public basic_socket_acceptor<boost::asio::local::stream_protocol::acceptor> { @@ -405,6 +422,7 @@ /** * \brief TLS/SSL acceptors. + * \ingroup acceptors * \tparam SocketAcceptor the socket connector (e.g. ip_acceptor) * * Wrap a SocketAcceptor object.
--- a/libirccd-core/irccd/connector.hpp Sun Nov 11 15:44:20 2018 +0100 +++ b/libirccd-core/irccd/connector.hpp Mon Nov 12 13:19:28 2018 +0100 @@ -24,6 +24,12 @@ * \brief Abstract connection interface. */ +/** + * \defgroup connectors Generic I/O connectors + * \ingroup networking + * \brief Generic I/O connectors. + */ + #include <cassert> #include <functional> #include <memory> @@ -43,6 +49,7 @@ /** * \brief Abstract connection interface. + * \ingroup connectors * * This class is used to connect to a stream end point (usually sockets) in an * asynchronous manner. @@ -83,6 +90,7 @@ /** * \brief Provide convenient functions for connectors. + * \ingroup connectors */ class socket_connector_base : public connector { protected: @@ -135,6 +143,7 @@ /** * \brief TCP/IP connector. + * \ingroup connectors */ class ip_connector : public socket_connector_base { public: @@ -268,6 +277,7 @@ /** * \brief Unix domain connector. + * \ingroup connectors */ class local_connector : public socket_connector_base { public: @@ -356,6 +366,7 @@ /** * \brief TLS/SSL connectors. + * \ingroup connectors * \tparam SocketConnector the socket connector (e.g. ip_connector) */ template <typename SocketConnector>
--- a/libirccd-core/irccd/stream.hpp Sun Nov 11 15:44:20 2018 +0100 +++ b/libirccd-core/irccd/stream.hpp Mon Nov 12 13:19:28 2018 +0100 @@ -24,6 +24,30 @@ * \brief Abstract stream interface. */ +/** + * \defgroup networking Networking + * \brief Networking + * + * Each irccd instance is controllable via sockets using JSON messages. + * + * This mechanism is offered via the triplet stream/acceptor/connector. Irccd + * uses different acceptors to wait for clients to connect and then construct + * a stream of it. Once ready, streams are ready to receive and send messages. + * + * On the client side (e.g. irccdctl), a generic connector is created to connect + * to the irccd instance. Once ready, a stream is also created and ready to + * perform the same receive and send messages. + * + * By default, irccd provides predefined implementations for TCP/IP, local unix + * sockets and optionally TLS over those. + */ + +/** + * \defgroup streams Generic I/O streams + * \ingroup networking + * \brief Generic I/O streams. + */ + #include <irccd/sysconfig.hpp> #include <cassert> @@ -46,6 +70,7 @@ /** * \brief Abstract stream interface + * \ingroup streams * * Abstract I/O interface that allows reading/writing from a stream in an * asynchronous manner. @@ -99,6 +124,7 @@ /** * \brief Abstract base interface for Boost.Asio sockets. + * \ingroup streams * * This class provides convenient functions for underlying sockets. * @@ -251,6 +277,7 @@ /** * \brief Complete implementation for basic sockets + * \ingroup streams * \tparam Socket Boost.Asio socket (e.g. boost::asio::ip::tcp::socket) */ template <typename Socket> @@ -327,6 +354,7 @@ /** * \brief Convenient alias for boost::asio::ip::tcp::socket + * \ingroup streams */ using ip_stream = basic_socket_stream<boost::asio::ip::tcp::socket>; @@ -338,6 +366,7 @@ /** * \brief Convenient alias for boost::asio::local::stream_protocol::socket + * \ingroup streams */ using local_stream = basic_socket_stream<boost::asio::local::stream_protocol::socket>; @@ -351,6 +380,7 @@ /** * \brief TLS/SSL streams. + * \ingroup streams * \tparam Socket the Boost.Asio compatible socket. */ template <typename Socket>
--- a/libirccd/irccd/daemon/command.hpp Sun Nov 11 15:44:20 2018 +0100 +++ b/libirccd/irccd/daemon/command.hpp Mon Nov 12 13:19:28 2018 +0100 @@ -24,6 +24,16 @@ * \brief Remote commands. */ +/** + * \defgroup commands Commands + * \brief Remote transport commands. + * + * The remote commands are server-side functions that can be called by clients + * connected to irccd. + * + * Example, the \ref irccd::server_message_command is used to send a message. + */ + #include <irccd/sysconfig.hpp> #include <functional> @@ -42,6 +52,7 @@ /** * \brief Server side remote command + * \ingroup commands */ class command { public: @@ -94,6 +105,7 @@ /** * \brief Implementation of plugin-config transport command. + * \ingroup commands * * Replies: * @@ -118,6 +130,7 @@ /** * \brief Implementation of plugin-info transport command. + * \ingroup commands * * Replies: * @@ -142,6 +155,7 @@ /** * \brief Implementation of plugin-list transport command. + * \ingroup commands */ class plugin_list_command : public command { public: @@ -162,6 +176,7 @@ /** * \brief Implementation of plugin-load transport command. + * \ingroup commands * * Replies: * @@ -188,6 +203,7 @@ /** * \brief Implementation of plugin-reload transport command. + * \ingroup commands * * Replies: * @@ -213,6 +229,7 @@ /** * \brief Implementation of plugin-unload transport command. + * \ingroup commands * * Replies: * @@ -238,6 +255,7 @@ /** * \brief Implementation of rule-add transport command. + * \ingroup commands * * Replies: * @@ -262,6 +280,7 @@ /** * \brief Implementation of rule-edit transport command. + * \ingroup commands * * Replies: * @@ -287,6 +306,7 @@ /** * \brief Implementation of rule-info transport command. + * \ingroup commands * * Replies: * @@ -311,6 +331,7 @@ /** * \brief Implementation of rule-list transport command. + * \ingroup commands */ class rule_list_command : public command { public: @@ -331,6 +352,7 @@ /** * \brief Implementation of rule-move transport command. + * \ingroup commands * * Replies: * @@ -355,6 +377,7 @@ /** * \brief Implementation of rule-remove transport command. + * \ingroup commands * * Replies: * @@ -379,6 +402,7 @@ /** * \brief Implementation of server-connect transport command. + * \ingroup commands * * Replies: * @@ -407,6 +431,7 @@ /** * \brief Implementation of server-disconnect transport command. + * \ingroup commands * * Replies: * @@ -432,6 +457,7 @@ /** * \brief Implementation of server-info transport command. + * \ingroup commands * * Replies: * @@ -457,6 +483,7 @@ /** * \brief Implementation of server-invite transport command. + * \ingroup commands * * Replies: * @@ -484,6 +511,7 @@ /** * \brief Implementation of server-join transport command. + * \ingroup commands * * Replies: * @@ -510,6 +538,7 @@ /** * \brief Implementation of server-kick transport command. + * \ingroup commands * * Replies: * @@ -537,6 +566,7 @@ /** * \brief Implementation of server-list transport command. + * \ingroup commands */ class server_list_command : public command { public: @@ -557,6 +587,7 @@ /** * \brief Implementation of server-me transport command. + * \ingroup commands * * Replies: * @@ -583,6 +614,7 @@ /** * \brief Implementation of server-message transport command. + * \ingroup commands * * Replies: * @@ -609,6 +641,7 @@ /** * \brief Implementation of server-mode transport command. + * \ingroup commands * * Replies: * @@ -636,6 +669,7 @@ /** * \brief Implementation of server-nick transport command. + * \ingroup commands * * Replies: * @@ -662,6 +696,7 @@ /** * \brief Implementation of server-notice transport command. + * \ingroup commands * * Replies: * @@ -688,6 +723,7 @@ /** * \brief Implementation of server-part transport command. + * \ingroup commands * * Replies: * @@ -714,6 +750,7 @@ /** * \brief Implementation of server-reconnect transport command. + * \ingroup commands * * Replies: * @@ -739,6 +776,7 @@ /** * \brief Implementation of server-topic transport command. + * \ingroup commands * * Replies: *
--- a/libirccd/irccd/daemon/irccd.hpp Sun Nov 11 15:44:20 2018 +0100 +++ b/libirccd/irccd/daemon/irccd.hpp Mon Nov 12 13:19:28 2018 +0100 @@ -24,6 +24,11 @@ * \brief Base class for irccd front end. */ +/** + * \defgroup services Services + * \brief All irccd services. + */ + #include <irccd/sysconfig.hpp> #include <memory>
--- a/libirccd/irccd/daemon/logger.hpp Sun Nov 11 15:44:20 2018 +0100 +++ b/libirccd/irccd/daemon/logger.hpp Mon Nov 12 13:19:28 2018 +0100 @@ -24,6 +24,23 @@ * \brief Logging facilities. */ +/** + * \brief Irccd logging system. + * \defgroup logger Loggers + */ + +/** + * \brief Predefined logger sinks. + * \defgroup logger-sinks Predefined logger sinks + * \ingroup logger + */ + +/** + * \brief Specialized loggable traits. + * \defgroup logger-traits Specialized loggable traits + * \ingroup logger + */ + #include <irccd/sysconfig.hpp> #include <memory> @@ -39,12 +56,32 @@ /** * \brief Traits for loggable objects. + * \ingroup logger-traits * * Specialize this structure and add the following static functions to be able * to log object with convenience: * + * ## get_category + * + * The get_category function should return a single word that describe the + * message entry category. + * + * Synopsis: + * * ```cpp * static auto get_category(const T&) noexcept -> std::string_view; + * ``` + * + * ## get_component + * + * The get_component function should return the identifier or any valid + * information about the given object that is useful for the user. + * + * If no information could be provided, an empty string can be returned. + * + * Synopsis: + * + * ```cpp * static auto get_component(const T&) noexcept -> std::string_view; * ``` */ @@ -53,6 +90,7 @@ /** * \brief Logger object. + * \ingroup logger */ class logger : public std::ostream, public std::stringbuf { private: @@ -81,6 +119,7 @@ /** * \brief Interface to implement new logger mechanisms. + * \ingroup logger-sinks * * Derive from this class and implement write_info, write_warning and * write_debug functions. @@ -251,6 +290,7 @@ /** * \brief Filter messages before printing them. + * \ingroup logger */ class filter { private: @@ -312,7 +352,8 @@ /** * \brief Logger implementation for console output using std::cout and - * std::cerr. + * std::cerr. + * \ingroup logger-sinks */ class console_sink : public sink { protected: @@ -334,6 +375,7 @@ /** * \brief Output to a files. + * \ingroup logger-sinks */ class file_sink : public sink { private: @@ -368,6 +410,7 @@ /** * \brief Use to disable logs. + * \ingroup logger-sinks * * Useful for unit tests when some classes may emits log. */ @@ -393,6 +436,7 @@ /** * \brief Implements logger into syslog. + * \ingroup logger-sinks */ class syslog_sink : public sink { protected:
--- a/libirccd/irccd/daemon/plugin.hpp Sun Nov 11 15:44:20 2018 +0100 +++ b/libirccd/irccd/daemon/plugin.hpp Mon Nov 12 13:19:28 2018 +0100 @@ -457,6 +457,10 @@ } // !irccd +/** + * \cond IRCCD_HIDDEN_SYMBOLS + */ + namespace std { template <> @@ -465,4 +469,8 @@ } // !std +/** + * \endcond + */ + #endif // !IRCCD_DAEMON_PLUGIN_HPP
--- a/libirccd/irccd/daemon/plugin_service.hpp Sun Nov 11 15:44:20 2018 +0100 +++ b/libirccd/irccd/daemon/plugin_service.hpp Mon Nov 12 13:19:28 2018 +0100 @@ -39,6 +39,7 @@ /** * \brief Manage plugins. + * \ingroup plugins * \ingroup services */ class plugin_service { @@ -256,6 +257,7 @@ /** * \brief Implement Loggable traits for plugin. + * \ingroup logger-traits */ template <> struct loggable_traits<plugin> {
--- a/libirccd/irccd/daemon/rule.hpp Sun Nov 11 15:44:20 2018 +0100 +++ b/libirccd/irccd/daemon/rule.hpp Mon Nov 12 13:19:28 2018 +0100 @@ -130,6 +130,10 @@ } // !irccd +/** + * \cond IRCCD_HIDDEN_SYMBOLS + */ + namespace std { template <> @@ -138,4 +142,8 @@ } // !std +/** + * \endcond + */ + #endif // !IRCCD_DAEMON_RULE_HPP
--- a/libirccd/irccd/daemon/rule_service.hpp Sun Nov 11 15:44:20 2018 +0100 +++ b/libirccd/irccd/daemon/rule_service.hpp Mon Nov 12 13:19:28 2018 +0100 @@ -129,6 +129,7 @@ /** * \brief Specialization for rule. + * \ingroup logger-traits */ template <> struct loggable_traits<rule> {
--- a/libirccd/irccd/daemon/server.hpp Sun Nov 11 15:44:20 2018 +0100 +++ b/libirccd/irccd/daemon/server.hpp Mon Nov 12 13:19:28 2018 +0100 @@ -25,8 +25,14 @@ */ /** - * \defgroup events IRC events + * \defgroup servers Servers + * \brief Everything you need for IRC server connection + */ + +/** + * \defgroup events Events * \brief Describe all IRC events. + * \ingroup servers */ #include <irccd/sysconfig.hpp> @@ -51,6 +57,7 @@ /** * \brief Prefixes for nicknames. + * \ingroup servers */ enum class channel_mode { creator = 'O', //!< Channel creator @@ -62,6 +69,7 @@ /** * \brief A channel to join with an optional password. + * \ingroup servers */ struct channel { std::string name; //!< the channel to join @@ -69,8 +77,8 @@ }; /** + * \brief Describe a whois information. * \ingroup events - * \brief Describe a whois information. */ struct whois_info { std::string nick; //!< user's nickname @@ -81,24 +89,24 @@ }; /** + * \brief Connection success event. * \ingroup events - * \brief Connection success event. */ struct connect_event { std::shared_ptr<class server> server; //!< The server. }; /** + * \brief Connection success event. * \ingroup events - * \brief Connection success event. */ struct disconnect_event { std::shared_ptr<class server> server; //!< The server. }; /** + * \brief Invite event. * \ingroup events - * \brief Invite event. */ struct invite_event { std::shared_ptr<class server> server; //!< The server. @@ -108,8 +116,8 @@ }; /** + * \brief Join event. * \ingroup events - * \brief Join event. */ struct join_event { std::shared_ptr<class server> server; //!< The server. @@ -118,8 +126,8 @@ }; /** + * \brief Kick event. * \ingroup events - * \brief Kick event. */ struct kick_event { std::shared_ptr<class server> server; //!< The server. @@ -130,8 +138,8 @@ }; /** + * \brief Message event. * \ingroup events - * \brief Message event. */ struct message_event { std::shared_ptr<class server> server; //!< The server. @@ -141,8 +149,8 @@ }; /** + * \brief CTCP action event. * \ingroup events - * \brief CTCP action event. */ struct me_event { std::shared_ptr<class server> server; //!< The server. @@ -152,8 +160,8 @@ }; /** + * \brief Mode event. * \ingroup events - * \brief Mode event. */ struct mode_event { std::shared_ptr<class server> server; //!< The server. @@ -166,8 +174,8 @@ }; /** + * \brief Names listing event. * \ingroup events - * \brief Names listing event. */ struct names_event { std::shared_ptr<class server> server; //!< The server. @@ -176,8 +184,8 @@ }; /** + * \brief Nick change event. * \ingroup events - * \brief Nick change event. */ struct nick_event { std::shared_ptr<class server> server; //!< The server. @@ -186,8 +194,8 @@ }; /** + * \brief Notice event. * \ingroup events - * \brief Notice event. */ struct notice_event { std::shared_ptr<class server> server; //!< The server. @@ -197,8 +205,8 @@ }; /** + * \brief Part event. * \ingroup events - * \brief Part event. */ struct part_event { std::shared_ptr<class server> server; //!< The server. @@ -208,8 +216,8 @@ }; /** + * \brief Topic event. * \ingroup events - * \brief Topic event. */ struct topic_event { std::shared_ptr<class server> server; //!< The server. @@ -219,8 +227,8 @@ }; /** + * \brief Whois event. * \ingroup events - * \brief Whois event. */ struct whois_event { std::shared_ptr<class server> server; //!< The server. @@ -228,8 +236,8 @@ }; /** + * \brief Store all possible events. * \ingroup events - * \brief Store all possible events. */ using event = std::variant< std::monostate, @@ -251,6 +259,7 @@ /** * \brief The class that connect to a IRC server. + * \ingroup server * * This class is higher level than irc connection, it does identify process, * parsing message, translating messages and queue'ing user requests. @@ -890,6 +899,10 @@ } // !irccd +/** + * \cond IRCCD_HIDDEN_SYMBOLS + */ + namespace std { template <> @@ -898,4 +911,8 @@ } // !std +/** + * \endcond + */ + #endif // !IRCCD_DAEMON_SERVER_HPP
--- a/libirccd/irccd/daemon/server_service.hpp Sun Nov 11 15:44:20 2018 +0100 +++ b/libirccd/irccd/daemon/server_service.hpp Mon Nov 12 13:19:28 2018 +0100 @@ -154,6 +154,7 @@ /** * \brief Specialization for server. + * \ingroup logger-traits */ template <> struct loggable_traits<server> {
--- a/libirccd/irccd/daemon/transport_client.hpp Sun Nov 11 15:44:20 2018 +0100 +++ b/libirccd/irccd/daemon/transport_client.hpp Mon Nov 12 13:19:28 2018 +0100 @@ -36,6 +36,7 @@ /** * \brief Abstract transport client class. + * \ingroup transports * * This class is responsible of receiving/sending data. */
--- a/libirccd/irccd/daemon/transport_server.hpp Sun Nov 11 15:44:20 2018 +0100 +++ b/libirccd/irccd/daemon/transport_server.hpp Mon Nov 12 13:19:28 2018 +0100 @@ -39,8 +39,7 @@ /** * \brief Abstract transport server class. - * - * # Synopsis + * \ingroup transports * * The transport_server class is an abstract interface that waits for clients to * connect and store them locally. It does not know the underlying @@ -49,7 +48,7 @@ * As only constraint the implementation must provide an asynchronous operation * to avoid blocking the daemon. * - * The derived class only have to implement do_accept function which is only + * The derived class only have to implement accept function which is only * responsible of getting a client ready for I/O (receiving and sending), the * transport_server does authentication and greeting by itself. * @@ -57,7 +56,7 @@ * * The connection procedure looks like this: * - * ``` + * ~~~ * o (transport_server::accept is called) * | * v [error] @@ -83,7 +82,7 @@ * +---------------------------------------+ [incorrect] | * | client is added to the list and ready ]-------------------------- + * +---------------------------------------+ - * ``` + * ~~~ * * # I/O procedures *
--- a/libirccd/irccd/daemon/transport_service.hpp Sun Nov 11 15:44:20 2018 +0100 +++ b/libirccd/irccd/daemon/transport_service.hpp Mon Nov 12 13:19:28 2018 +0100 @@ -24,6 +24,11 @@ * \brief Transport service. */ +/** + * \defgroup transports Transports + * \brief Transport client and servers + */ + #include <memory> #include <vector> @@ -38,8 +43,9 @@ class transport_server; /** - * \brief manage transport servers and clients. + * \brief Manage transport servers and clients. * \ingroup services + * \ingroup transports */ class transport_service { public: