From bca742c37f390502765dfe50c1b18111c9c538cf Mon Sep 17 00:00:00 2001 From: Kevin Matz Date: Tue, 15 Nov 2022 11:32:29 -0500 Subject: [PATCH] Documentation improvement and cleanup --- protocol/acn/component.h | 72 +++++++++++++++++++++------------------ protocol/acn/pdu-stream.h | 7 ++-- protocol/acn/pdu.h | 10 +++++- protocol/dmp/dmp.h | 4 ++- protocol/dmx/dmx.h | 3 ++ protocol/dmx/universe.h | 4 +-- protocol/otp/otp.h | 3 ++ protocol/rdm/E1.37-1.h | 3 +- protocol/rdm/E1.37-2.h | 3 +- protocol/rdm/E1.37-7.h | 3 +- protocol/rdm/rdm.h | 3 ++ protocol/rdmnet/rdmnet.h | 3 ++ protocol/rlp/rlp.h | 7 ++++ protocol/sdt/sdt.h | 6 ++-- protocol/sdt/udp.h | 2 +- protocol/uuid/uuid.h | 4 +-- 16 files changed, 89 insertions(+), 48 deletions(-) diff --git a/protocol/acn/component.h b/protocol/acn/component.h index 71aa56e..73189b7 100644 --- a/protocol/acn/component.h +++ b/protocol/acn/component.h @@ -27,20 +27,29 @@ #include +/** + * @brief @cite ACN Architecture for Control Networks + */ namespace ACN { /** - * @brief The Component class - * The process, program or application corresponding to a single ACN endpoint. - * All messages in ACN are sent and received by a component. + * @brief The process, program or application corresponding to a single ACN endpoint. * - * See [Arch] for a more complete definition. + * All messages in ACN are sent and received by a component. + * See @cite ACN [Arch] for a more complete definition. + * + * @cite epi19 **EPI 19: ACN Discovery on IP Networks** + * + * (3) Component Name Strings + * Each component shall maintain two text identifier strings intended to + * indicate the function of the component in human readable terms for + * browsing purposes. */ class Component { public: /** * @brief Component - * @param cid + * @param cid the Component Identifier */ Component(UUID::uuid cid = UUID::uuid()) : fctn_(std::string("OpenLCP ACN Component")) @@ -49,51 +58,46 @@ public: {}; /** - * @brief cid - * @return + * @brief Component Identifier + * @return the CID + * + * @cite ACN 1.2.3: In ACN each distinct endpoint transmitting and receiving ACN data is called a + * Component and all ACN communications take place between components. Each ACN component has a + * component identifier or CID which is unique not just within the system but across the whole + * world and does not change with time. */ const UUID::uuid cid() const { return cid_; } + /** - * @brief fixedName fixed component name - * @return + * @brief @cite epi19 3.1 Fixed Component Type Name (FCTN) + * @return the FCTN + * + * Shall be a UTF-8 string that is assigned during manufacture. */ const std::string fixedName() const { return fctn_; } /** - * @brief userName user-asigned name - * @return + * @brief @cite epi19 3.2 User Assigned Component Name (UACN) + * @return the UACN + * + * Shall be a UTF-8 string that may be assigned by the user. */ const std::string userName() const { return uacn_; } /** - * @brief component name, either user asigned or fixed. - * @return + * @brief Component Name, either User Asigned or Fixed. + * @return a name */ const std::string name() const { return uacn_.empty() ? fctn_ : uacn_; } /** - * @brief set the user asigned name - * @param s + * @brief Set the User Asigned Component Name (UACN). + * @param s UACN Name string + * + * If not an empty string, will be prefered over the FCTN. */ void assignUserName(const std::string s) { uacn_ = s; } protected: - /** - * EPI 19: ACN Discovery on IP Networks - * 3. Component Name Strings - * Each component shall maintain two text identifier strings intended to - * indicate the function of the component in human readable terms for - * browsing purposes. - */ - - /** - * @brief 3.1. Fixed Component Type Name (FCTN) - * shall be a UTF-8 string that is assigned during manufacture. - */ - std::string fctn_; - - /** - * @brief 3.2. User Assigned Component Name (UACN) - * shall be a UTF-8 string that may be assigned by the user. - */ - std::string uacn_; + std::string fctn_; //!< Fixed Component Type Name (FCTN) + std::string uacn_; //!< User Assigned Component Name (UACN) private: const UUID::uuid cid_; diff --git a/protocol/acn/pdu-stream.h b/protocol/acn/pdu-stream.h index b3415c5..dba66c3 100644 --- a/protocol/acn/pdu-stream.h +++ b/protocol/acn/pdu-stream.h @@ -30,7 +30,7 @@ namespace ACN::PDU { -struct pdu_stream_object; +struct pdu_stream_object; // forward declare /** * @brief Input/Output stream of nested PDU @@ -118,11 +118,14 @@ public: }; +/** + * @brief A shared pointer to pdu_stream. + */ using Stream = std::shared_ptr; /** - * @brief The pdu_stream_object struct + * @brief The inheritable base of data objects that can be read from and written to a pdu_stream. */ struct pdu_stream_object { diff --git a/protocol/acn/pdu.h b/protocol/acn/pdu.h index 4f4d0cc..2d49b6d 100644 --- a/protocol/acn/pdu.h +++ b/protocol/acn/pdu.h @@ -28,6 +28,14 @@ #include #include "pdu-stream.h" +/** + * @brief @cite ACN 1.2.8.1 Common Packet Format + * + * In developing SDT and DMP it was recognized that the messages in both protocols have many + * similarities and that by using a common message format across all the ACN protocols, the code to + * recognize and decode messages can be shared across different message types. This is why ACN + * defines a common message format the Protocol Data Unit or PDU. + */ namespace ACN::PDU { class Pdu; // forward declare @@ -111,7 +119,7 @@ struct Block /** - * @brief 2.4.1. Flags + * @brief @cite ACN 2.4.1 Flags * * Flags is a 4-bit field containing flags L, V, H and D which declare how * the PDU is packed. diff --git a/protocol/dmp/dmp.h b/protocol/dmp/dmp.h index 8620262..eb0c21c 100644 --- a/protocol/dmp/dmp.h +++ b/protocol/dmp/dmp.h @@ -28,7 +28,9 @@ #include #include "acn/pdu.h" -// Architecture for Control Networks – Device Management Protocol +/** + * @brief @cite DMP Architecture for Control Networks – Device Management Protocol + */ namespace ACN::DMP { /** diff --git a/protocol/dmx/dmx.h b/protocol/dmx/dmx.h index ee86e97..2f721ea 100644 --- a/protocol/dmx/dmx.h +++ b/protocol/dmx/dmx.h @@ -25,6 +25,9 @@ #include +/** + * @brief @cite DMX The Digital Multiplex Protocol + */ namespace DMX { /// \cite DMX diff --git a/protocol/dmx/universe.h b/protocol/dmx/universe.h index ccd3bb0..12f4d9e 100644 --- a/protocol/dmx/universe.h +++ b/protocol/dmx/universe.h @@ -36,8 +36,8 @@ namespace DMX { class Universe; // forward declare the Univserse class -using DimmerData = std::array; -using DataHandler = std::function; +using DimmerData = std::array; //!< Array of 513 bytes for basic data. +using DataHandler = std::function; //!< Callback function for data handling. /** * @brief The Universe class diff --git a/protocol/otp/otp.h b/protocol/otp/otp.h index 86d3ae3..3a6c6af 100644 --- a/protocol/otp/otp.h +++ b/protocol/otp/otp.h @@ -25,6 +25,9 @@ #include +/** + * @brief @cite OTP The Object Transform Protocol + */ namespace OTP { static const uint8_t OTP_PACKET_IDENTIFIER[] = { 0x4f, 0x54, 0x50, 0x2d, 0x45, 0x31, 0x2e, 0x35, diff --git a/protocol/rdm/E1.37-1.h b/protocol/rdm/E1.37-1.h index 3a759c1..113e9f0 100644 --- a/protocol/rdm/E1.37-1.h +++ b/protocol/rdm/E1.37-1.h @@ -26,7 +26,8 @@ #include /** - * @brief ANSI E1.37-1 – 2012 (R2017) + * \ingroup RDM + * \details ANSI E1.37-1 – 2012 (R2017) * Additional Message Sets for ANSI E1.20 (RDM) – Part 1, * Dimmer Message Sets */ diff --git a/protocol/rdm/E1.37-2.h b/protocol/rdm/E1.37-2.h index 84d6f8c..67eb11f 100644 --- a/protocol/rdm/E1.37-2.h +++ b/protocol/rdm/E1.37-2.h @@ -26,7 +26,8 @@ #include /** - * @brief ANSI E1.37-2 – 2015 Entertainment Technology + * \ingroup RDM + * \details ANSI E1.37-2 – 2015 Entertainment Technology * Additional Message Sets for ANSI E1.20 (RDM) – Part 2, * IPv4 & DNS Configuration Messages */ diff --git a/protocol/rdm/E1.37-7.h b/protocol/rdm/E1.37-7.h index ec731e6..f35ce1e 100644 --- a/protocol/rdm/E1.37-7.h +++ b/protocol/rdm/E1.37-7.h @@ -26,7 +26,8 @@ #include /** - * @brief ANSI E1.37-7 + * \ingroup RDM + * \details ANSI E1.37-7 * Additional Message Sets for ANSI E1.20 (RDM) - * Gateway & Splitter Configuration Messages */ diff --git a/protocol/rdm/rdm.h b/protocol/rdm/rdm.h index ec88fff..08ca4f8 100644 --- a/protocol/rdm/rdm.h +++ b/protocol/rdm/rdm.h @@ -30,6 +30,9 @@ #include +/** + * @brief \cite RDM The Remote Device Management Protocol + */ namespace RDM { using PID = uint16_t; //!< Parameter Identification number diff --git a/protocol/rdmnet/rdmnet.h b/protocol/rdmnet/rdmnet.h index edd865f..1b86e2d 100644 --- a/protocol/rdmnet/rdmnet.h +++ b/protocol/rdmnet/rdmnet.h @@ -25,6 +25,9 @@ #include "rdm/rdm.h" +/** + * @brief @cite RDMnet The RDMnet Protocol + */ namespace RDMnet { using RDM::PID; diff --git a/protocol/rlp/rlp.h b/protocol/rlp/rlp.h index 81f07c1..68da809 100644 --- a/protocol/rlp/rlp.h +++ b/protocol/rlp/rlp.h @@ -28,6 +28,13 @@ #include "acn/pdu.h" #include "uuid/uuid.h" +/** + * @brief @cite ACN 2.3.2 The Root Layer Protocol + * + * The lowest ACN layer above the underlying transport (e.g. the contents of a UDP packet) is + * handled by the ACN Root Layer Protocol. The Root Layer protocol may be tailored to fit higher + * ACN protocols onto each individual transport. + */ namespace ACN::RLP { /** diff --git a/protocol/sdt/sdt.h b/protocol/sdt/sdt.h index 0a97d3d..39334e6 100644 --- a/protocol/sdt/sdt.h +++ b/protocol/sdt/sdt.h @@ -26,8 +26,10 @@ #include "acn/pdu.h" #include "udp.h" // EPI 18 -// ANSI E1.17- 2015, Architecture for Control Networks– -// Session Data Transport Protocol +/** + * @brief @cite SDT ANSI E1.17- 2015, Architecture for Control Networks– + * Session Data Transport Protocol + */ namespace ACN::SDT { /** diff --git a/protocol/sdt/udp.h b/protocol/sdt/udp.h index 7699ba8..43cf95b 100644 --- a/protocol/sdt/udp.h +++ b/protocol/sdt/udp.h @@ -23,7 +23,7 @@ */ #pragma once -#include "acn/pdu.h" +#include "acn/pdu-stream.h" #include // ACN EPI 18 - Operation of SDT on UDP Networks diff --git a/protocol/uuid/uuid.h b/protocol/uuid/uuid.h index 54935f1..3228017 100644 --- a/protocol/uuid/uuid.h +++ b/protocol/uuid/uuid.h @@ -30,9 +30,9 @@ #define UUID_LENGTH 16 /** - * @brief RFC4122 A Universally Unique IDentifier (UUID) URN Namespace + * @brief \cite uuid RFC4122 A Universally Unique IDentifier (UUID) URN Namespace * - * > \cite uuid This specification defines a Uniform Resource Name namespace + * > This specification defines a Uniform Resource Name namespace * > for UUIDs (Universally Unique IDentifier), also known as GUIDs (Globally * > Unique IDentifier). A UUID is 128 bits long, and can guarantee uniqueness * > across space and time. UUIDs were originally used in the Apollo Network