Document Arduino_open62541 library using Doxygen and "render-docs" tool. (#19)

Author: aentinger

.github/workflows/render-documentation.yml

@@ -25,5 +25,5 @@ jobs:
     with:
       source-path: './src'
       target-path: './docs/api.md'
-      exclude-pattern: '*/open62541/* open62541.h'
+      exclude-pattern: '*/open62541/* open62541.h o1heap.h'
       commit: ${{ github.event_name != 'pull_request' }} # Only commit changes if not a PR

.gitignore

@@ -1,3 +1,5 @@
 .vscode/
 .idea/
 node_modules
+doxygen-build/
+moxygen.log

docs/api.md

@@ -146,18 +146,18 @@ void
 Opta::add_analog_input(
   UA_Server * server,
   const char * display_name,
-  AnalogInput::OnReadRequestFunc const on_read_request_func)
+  AnalogInput::OnReadRequestFunc const on_read_request)
 {
-  _analog_input_mgr->add_analog_input(server, display_name, on_read_request_func);
+  _analog_input_mgr->add_analog_input(server, display_name, on_read_request);
 }
 
 void
 Opta::add_digital_input(
   UA_Server * server,
   const char * display_name,
-  DigitalInput::OnReadRequestFunc const on_read_request_func)
+  DigitalInput::OnReadRequestFunc const on_read_request)
 {
-  _digital_input_mgr->add_digital_input(server, display_name, on_read_request_func);
+  _digital_input_mgr->add_digital_input(server, display_name, on_read_request);
 }
 
 void

src/Opta.cpp

@@ -29,49 +29,100 @@
  * NAMESPACE
  **************************************************************************************/
 
+/**
+ * opcua is used as enclosing namespace for all parts of the Arduino_open62541 library
+ * in order to avoid naming conflicts with already existing frameworks pertaining the
+ * Arduino Opta.
+ */
 namespace opcua
 {
 
 /**************************************************************************************
  * CLASS DECLARATION
  **************************************************************************************/
 
+/**
+ * @class Opta
+ * @brief Provides functions for exposing various IO capabilities of the Arduino Opta via OPC UA.
+ *
+ * This class allows the user to expose analog and digital inputs, as well as relay and LED outputs
+ * via OPC UA properties.
+ */
 class Opta
 {
 public:
+  /**
+   * SharedPtr is std::shared_ptr of an Opta class.
+   */
   typedef std::shared_ptr<Opta> SharedPtr;
 
 
+  /**
+   * Creates a new instance of the opcua::Opta class, creating an OPC UA object abstraction in the process.
+   * @param server Pointer to the OPC UA server implementation of the open62541 library.
+   * @param opta_type Enumerated type describing which Opta (WiFi, RS485, Lite) variant is being created.
+   * @return std::shared_ptr holding the newly allocated instance of opcua::Opta.
+   */
   static SharedPtr
   create(
     UA_Server * server,
     OptaVariant::Type const opta_type);
 
 
+  /**
+   * Constructor of the opcua::Opta class.
+   * @param server Pointer to the OPC UA server implementation of the open62541 library.
+   * @param node_id OPC UA node id uniquely identifying the OPC UA representation of the opcua::Opta class as an OPC UA object node.
+   * @param opta_type Enumerated type describing which Opta (WiFi, RS485, Lite) variant is being created.
+   */
   Opta(
     UA_Server * server,
     UA_NodeId const & node_id,
     OptaVariant::Type const opta_type);
 
 
+  /**
+   * Adds an analog input to the opcua::Opta object node and exposes it as an OPC UA variable node.
+   * @param server Pointer to the OPC UA server implementation of the open62541 library.
+   * @param display_name Character string providing an easy identifiable name for the variable node.
+   * @param on_read_request Function pointer which is called during a read-access on the variable node representing the analog input.
+   */
   void
   add_analog_input(
     UA_Server * server,
     const char * display_name,
-    AnalogInput::OnReadRequestFunc const on_read_request_func);
-
+    AnalogInput::OnReadRequestFunc const on_read_request);
+
+  /**
+   * Adds a digital input to the opcua::Opta object node and exposes it as an OPC UA variable node.
+   * @param server Pointer to the OPC UA server implementation of the open62541 library.
+   * @param display_name Character string providing an easy identifiable name for the variable node.
+   * @param on_read_request Function pointer which is called during a read-access on the variable node representing the digital input.
+   */
   void
   add_digital_input(
     UA_Server * server,
     const char * display_name,
-    DigitalInput::OnReadRequestFunc const on_read_request_func);
-
+    DigitalInput::OnReadRequestFunc const on_read_request);
+
+  /**
+   * Adds a relay output to the opcua::Opta object node and exposes it as an OPC UA variable node.
+   * @param server Pointer to the OPC UA server implementation of the open62541 library.
+   * @param display_name Character string providing an easy identifiable name for the variable node.
+   * @param on_set_relay_state Function pointer which is called during a write-access on the variable node representing the relay output.
+   */
   void
   add_relay_output(
     UA_Server * server,
     const char * display_name,
     Relay::OnSetRelayStateFunc const on_set_relay_state);
 
+  /**
+   * Adds a LED output to the opcua::Opta object node and exposes it as an OPC UA variable node.
+   * @param server Pointer to the OPC UA server implementation of the open62541 library.
+   * @param display_name Character string providing an easy identifiable name for the variable node.
+   * @param on_set_led_state Function pointer which is called during a write-access on the variable node representing the LED output.
+   */
   void
   add_led_output(
     UA_Server * server,

src/Opta.h

@@ -32,28 +32,71 @@ namespace opcua
  * CLASS DECLARATION
  **************************************************************************************/
 
+/**
+ * @class OptaExpansionManager
+ * @brief High-level class to create OPC UA representations for Arduino Opta digital and analog expansion boards.
+ *
+ * This class allows the user to create OPC UA representations of digital (mechanical and solid-state relays) as
+ * well as analog expansion boards connected to the Arduino Opta.
+ */
 class OptaExpansionManager
 {
 public:
+  /**
+   * SharedPtr is std::shared_ptr of an OptaExpansionManager class.
+   */
   typedef std::shared_ptr<OptaExpansionManager> SharedPtr;
 
 
+  /**
+   * Creates a new instance of the opcua::OptaExpansionManager class.
+   * @param server Pointer to the OPC UA server implementation of the open62541 library.
+   * @return std::shared_ptr holding the newly allocated instance of opcua::OptaExpansionManager.
+   */
   static SharedPtr
   create(
     UA_Server * server) {
     return std::make_shared<OptaExpansionManager>(server);
   }
 
 
+  /**
+   * Constructor of the opcua::OptaExpansionManager class.
+   * @param server Pointer to the OPC UA server implementation of the open62541 library.
+   */
   OptaExpansionManager(
     UA_Server * server)
   : _server{server}
   { }
 
 
-  DigitalMechExpansion::SharedPtr create_digital_mechanical_expansion(uint8_t const exp_num);
-  DigitalStSolidExpansion::SharedPtr create_digital_solid_state_expansion(uint8_t const exp_num);
-  AnalogExpansion::SharedPtr create_analog_expansion(uint8_t const exp_num);
+  /**
+   * Creates a new instance of the opcua::DigitalMechExpansion (digital expansion with mechanical relays) class.
+   * @param exp_num A numerical identifier provided by the Arduino_Opta_Blueprint library and identifying the number of the expansion module in the daisy-chain of expansion modules, i.e. exp_num = 2 refers to the second connect expansion module.
+   * @return std::shared_ptr holding the newly allocated instance of opcua::DigitalMechExpansion.
+   */
+  DigitalMechExpansion::SharedPtr
+  create_digital_mechanical_expansion(
+    uint8_t const exp_num);
+
+  /**
+   * Creates a new instance of the opcua::DigitalStSolidExpansion (digital expansion with solid-state relays) class.
+   * @param exp_num A numerical identifier provided by the Arduino_Opta_Blueprint library and identifying the number of the expansion module in the daisy-chain of expansion modules, i.e. exp_num = 2 refers to the second connect expansion module.
+   * @return std::shared_ptr holding the newly allocated instance of opcua::DigitalStSolidExpansion.
+   */
+  DigitalStSolidExpansion::SharedPtr
+  create_digital_solid_state_expansion(
+    uint8_t const exp_num);
+
+  /**
+   * Creates a new instance of the opcua::AnalogExpansion class.
+   * @param exp_num A numerical identifier provided by the Arduino_Opta_Blueprint library and identifying the number of the expansion module in the daisy-chain of expansion modules, i.e. exp_num = 2 refers to the second connect expansion module.
+   * @return std::shared_ptr holding the newly allocated instance of opcua::AnalogExpansion.
+   */
+  AnalogExpansion::SharedPtr
+  create_analog_expansion(
+    uint8_t const exp_num);
+
 
 private:
   UA_Server * _server;

src/OptaExpansionManager.h

@@ -26,23 +26,63 @@ namespace opcua
  * CLASS DECLARATION
  **************************************************************************************/
 
+/**
+ * @class OptaVariant
+ * @brief Enables determination of Opta variant (WiFi, RS485, Lite) on which the OPC UA firmware is running on.
+ *
+ * This class allows the user to determine the concrete Opta variant (WiFi, RS485, Lite) on which the OPC UA
+ * firmware is running on. This is archived by interrogating information stored by the bootloader.
+ */
 class OptaVariant
 {
 public:
+  /**
+   * The constructor of OptaVariant is deleted because this object shall not be instantiated.
+   */
   OptaVariant() = delete;
+  /**
+   * The copy constructor of OptaVariant is deleted because this object shall not be copied.
+   */
   OptaVariant(OptaVariant const &) = delete;
 
 
-  enum class Type { Lite, RS485, WiFi };
+  /**
+   * Type is an enumeration type to describe the various different Arduino Opta variants.
+   */
+  enum class Type
+  {
+    /** Arduino Opta Lite */
+    Lite,
+    /** Arduino Opta RS485 */
+    RS485,
+    /** Arduino Opta WiFi */
+    WiFi
+  };
 
 
+  /**
+   * Determines the current Opta variant by reading information provided by the bootloader.
+   * @param type Output parameter containing the current Opta variant.
+   * @return True if the Opta variant could be obtained successfully.
+   */
   static bool
   get_opta_variant(
     Type & type);
 
+  /**
+   * Convert enumerated variant type to variant product name.
+   * @param type Enumerated type describing an Opta variant.
+   * @return String describing the Opta variant's product name, i.e. Type::Lite -> "Arduino Opta Lite"
+   */
   static std::string
     toString(
       Type const type);
+
+  /**
+   * Convert enumerated variant type to variant product SKU number.
+   * @param type Enumerated type describing an Opta variant.
+   * @return String describing the Opta variant's SKU number, i.e. Type::Lite -> "AFX00003"
+   */
   static std::string
     toSKUString(
       Type const type);

src/OptaVariant.h

@@ -69,19 +69,19 @@ void
 AnalogExpansion::add_analog_input(
   UA_Server * server,
   const char * display_name,
-  AnalogInput::OnReadRequestFunc const on_read_request_func)
+  AnalogInput::OnReadRequestFunc const on_read_request)
 {
-  _analog_input_mgr->add_analog_input(server, display_name, on_read_request_func);
+  _analog_input_mgr->add_analog_input(server, display_name, on_read_request);
 }
 
 void
 AnalogExpansion::add_analog_output(
   UA_Server * server,
   const char * display_name,
   AnalogOutput::OnReadRequestFunc const on_read_request,
-  AnalogOutput::OnWriteRequestFunc const on_write_request_func)
+  AnalogOutput::OnWriteRequestFunc const on_write_request)
 {
-  _analog_output_mgr->add_analog_output(server, display_name, on_read_request, on_write_request_func);
+  _analog_output_mgr->add_analog_output(server, display_name, on_read_request, on_write_request);
 }
 
 void