From 66f5600450ee0acb3836c5f35f641656798404e5 Mon Sep 17 00:00:00 2001
From: Felix Mauch <mauch@fzi.de>
Date: Tue, 24 Sep 2019 18:32:01 +0200
Subject: [PATCH] Documented tool_communication

---
 .../ur_rtde_driver/ur/tool_communication.h    | 81 ++++++++++++++++++-
 ur_rtde_driver/src/ur/tool_communication.cpp  |  2 +-
 2 files changed, 78 insertions(+), 5 deletions(-)

diff --git a/ur_rtde_driver/include/ur_rtde_driver/ur/tool_communication.h b/ur_rtde_driver/include/ur_rtde_driver/ur/tool_communication.h
index 85b9228..d92ea09 100644
--- a/ur_rtde_driver/include/ur_rtde_driver/ur/tool_communication.h
+++ b/ur_rtde_driver/include/ur_rtde_driver/ur/tool_communication.h
@@ -34,13 +34,19 @@
 
 namespace ur_driver
 {
+/*!
+ * \brief Possible values for the tool voltage
+ */
 enum class ToolVoltage : int
 {
-  OFF = 0,
-  _12V = 12,
-  _24V = 24
+  OFF = 0,    ///< 0V
+  _12V = 12,  ///< 12V
+  _24V = 24   ///< 24V
 };
 
+/*!
+ * \brief Possible values for th parity flag
+ */
 enum class Parity : int
 {
   NONE = 0,
@@ -62,11 +68,24 @@ public:
 
   using Datatype = T;
 
+  /*!
+   * \brief Create a new Limited object
+   *
+   * \param lower Lower boundary used for this Limited object
+   * \param upper Upper boundary used for this Limited object
+   */
   Limited(const T lower, const T upper) : lower_(lower), upper_(upper)
   {
     data_ = lower_;
   }
 
+  /*!
+   * \brief Set the data field with a given value
+   *
+   * If the given value is out of the configured range, an exception is thrown.
+   *
+   * \param data
+   */
   void setData(const T data)
   {
     if (data >= lower_ && data <= upper_)
@@ -79,6 +98,9 @@ public:
     }
   }
 
+  /*!
+   * \brief Returns the data stored in this object
+   */
   T getData() const
   {
     return data_;
@@ -103,59 +125,110 @@ public:
   using RxIdleCharsT = Limited<float>;
   using TxIdleCharsT = Limited<float>;
 
+  /*!
+   * \brief Setup the tool voltage that will be configured on the robot. This will not immediately
+   * change values on the robot, it will only be stored inside the ToolCommSetup object.
+   */
   void setToolVoltage(const ToolVoltage tool_voltage)
   {
     tool_voltage_ = tool_voltage;
   }
+
+  /*!
+   * \brief Return the tool voltage currently stored
+   */
   ToolVoltage getToolVoltage() const
   {
     return tool_voltage_;
   }
 
+  /*!
+   * \brief Setup the tool communication parity that will be configured on the robot. This will not immediately
+   * change values on the robot, it will only be stored inside the ToolCommSetup object.
+   */
   void setParity(const Parity parity)
   {
     parity_ = parity;
   }
+  /*!
+   * \brief Return the parity currently stored
+   */
   Parity getParity() const
   {
     return parity_;
   }
 
+  /*!
+   * \brief Setup the tool communication baud rate that will be configured on the robot. This will not immediately
+   * change values on the robot, it will only be stored inside the ToolCommSetup object.
+   *
+   * \param baud_rate must be one of baud_rates_allowed_ or an exception will be thrown
+   */
   void setBaudRate(const uint32_t baud_rate);
+  /*!
+   * \brief Return the baud rate currently stored
+   */
   uint32_t getBaudRate() const
   {
     return baud_rate_;
   };
 
+  /*!
+   * \brief Setup the tool communication number of stop bits that will be configured on the robot. This will not
+   * immediately change values on the robot, it will only be stored inside the ToolCommSetup object.
+   *
+   * \param stop_bits must be inside [1,2] or this will throw an exception.
+   */
   void setStopBits(const StopBitsT::Datatype stop_bits)
   {
     stop_bits_.setData(stop_bits);
   }
+  /*!
+   * \brief Return the number of stop bits currently stored
+   */
   StopBitsT::Datatype getStopBits() const
   {
     return stop_bits_.getData();
   }
 
+  /*!
+   * \brief Setup the tool communication number of idle chars for the rx channel that will be configured on the robot.
+   * This will not immediately change values on the robot, it will only be stored inside the ToolCommSetup object.
+   *
+   * \param rx_idle_chars must be inside [1.0, 40] or this will throw an exception.
+   */
   void setRxIdleChars(const RxIdleCharsT::Datatype rx_idle_chars)
   {
     rx_idle_chars_.setData(rx_idle_chars);
   }
+  /*!
+   * \brief Return the number of rx idle chars currently stored
+   */
   RxIdleCharsT::Datatype getRxIdleChars() const
   {
     return rx_idle_chars_.getData();
   }
 
+  /*!
+   * \brief Setup the tool communication number of idle chars for the tx channel that will be configured on the robot.
+   * This will not immediately change values on the robot, it will only be stored inside the ToolCommSetup object.
+   *
+   * \param rx_idle_chars must be inside [0.0, 40] or this will throw an exception.
+   */
   void setTxIdleChars(const TxIdleCharsT::Datatype tx_idle_chars)
   {
     tx_idle_chars_.setData(tx_idle_chars);
   }
+  /*!
+   * \brief Return the number of tx idle chars currently stored
+   */
   TxIdleCharsT::Datatype getTxIdleChars() const
   {
     return tx_idle_chars_.getData();
   }
 
 private:
-  const std::set<uint32_t> baud_rates_{ 9600, 19200, 38400, 57600, 115200, 10000000, 2000000, 5000000 };
+  const std::set<uint32_t> baud_rates_allowed_{ 9600, 19200, 38400, 57600, 115200, 10000000, 2000000, 5000000 };
 
   ToolVoltage tool_voltage_;
   Parity parity_;
diff --git a/ur_rtde_driver/src/ur/tool_communication.cpp b/ur_rtde_driver/src/ur/tool_communication.cpp
index df87740..fade5ea 100644
--- a/ur_rtde_driver/src/ur/tool_communication.cpp
+++ b/ur_rtde_driver/src/ur/tool_communication.cpp
@@ -41,7 +41,7 @@ ToolCommSetup::ToolCommSetup()
 
 void ToolCommSetup::setBaudRate(const uint32_t baud_rate)
 {
-  if (baud_rates_.find(baud_rate) != baud_rates_.end())
+  if (baud_rates_allowed_.find(baud_rate) != baud_rates_allowed_.end())
   {
     baud_rate_ = baud_rate;
   }