Add documentation for UrDriverConfiguration struct

Author: urfeex

include/ur_client_library/ur/ur_driver.h

@@ -44,31 +44,78 @@
 
 namespace urcl
 {
+/*!
+ * \brief Structure for configuration parameters of a UrDriver object.
+ */
 struct UrDriverConfiguration
 {
-  std::string robot_ip;
-  std::string script_file;
-  std::string output_recipe_file;
-  std::string input_recipe_file;
+  std::string robot_ip;            //!< IP-address under which the robot is reachable.
+  std::string script_file;         //!< URScript file that should be sent to the robot.
+  std::string output_recipe_file;  //!< Filename where the output recipe is stored in.
+  std::string input_recipe_file;   //!< Filename where the input recipe is stored in.
+
+  /*!
+   * \brief Function handle to a callback on program state changes.
+   *
+   * For this to work, the URScript program will have to send keepalive signals to the \p
+   * reverse_port.
+   */
   std::function<void(bool)> handle_program_state;
-  bool headless_mode;
+  bool headless_mode;  //!< Parameter to control if the driver should be started in headless mode.
 
-  std::unique_ptr<ToolCommSetup> tool_comm_setup = nullptr;
+  std::unique_ptr<ToolCommSetup> tool_comm_setup = nullptr;  //!< Configuration for using the tool communication.
 
+  /*!
+   * \brief Port that will be opened by the driver to allow direct communication between the driver
+   * and the robot controller.
+   */
   uint32_t reverse_port = 50001;
+
+  /*! \brief The driver will offer an interface to receive the program's URScript on this port. If
+   * the robot cannot connect to this port, `External Control` will stop immediately.
+   */
   uint32_t script_sender_port = 50002;
+
+  /*!
+   * \brief Port used for sending trajectory points to the robot in case of trajectory forwarding.
+   */
   uint32_t trajectory_port = 50003;
+
+  /*!
+   * \brief Port used for forwarding script commands to the robot.
+   *
+   * This interface supports a set of predefined commands.
+   * The script commands will be executed locally on the robot.
+   */
   uint32_t script_command_port = 50004;
+
+  /*!
+   * \brief IP address that the reverse_port will get bound to.
+   *
+   * If not specified, the IP address of the interface that is used for connecting to the robot's RTDE port will be
+   * used.
+   */
   std::string reverse_ip = "";
 
+  /*!
+   * \brief Proportional gain for arm joints following target position, range [100,2000]
+   */
   int servoj_gain = 2000;
+
+  /*!
+   * \brief Time [S], range [0.03,0.2] smoothens servoj calls with this lookahead time
+   */
   double servoj_lookahead_time = 0.03;
 
   bool non_blocking_read = false;
 
   // TODO: Remove on 2027-05
+  // The following parameters are considered deprecated and will be removed in May 2027.
+  /// @private
   std::string calibration_checksum = "";
+  /// @private
   double force_mode_damping = 0.025;
+  /// @private
   double force_mode_gain_scaling = 0.5;
 };
 
@@ -82,13 +129,27 @@ struct UrDriverConfiguration
 class UrDriver
 {
 public:
+  /*!
+   * \brief Constructs a new UrDriver object.
+   *
+   * An RTDE connection to the robot will be established using the given recipe files. However, RTDE
+   * communication will not be started automatically, as this requires an external structure to read
+   * data from the RTDE client using the getDataPackage() method periodically. Once this is setup,
+   * please use the startRTDECommunication() method to actually start RTDE communication.
+   *
+   * \param config Configuration struct for the UrDriver. See it's documentation for details.
+   */
   explicit UrDriver(const UrDriverConfiguration& config)
   {
     init(config);
   }
 
   /*!
    * \brief Constructs a new UrDriver object.
+   *
+   * \deprecated Initializing a UrDriver object with an argument list is deprecated. Please use UrDriver(const
+   *             UrDriverConfiguration& config) instead. This function will be removed in May 2027.
+   *
    * Upon initialization this class will check the calibration checksum reported from the robot and
    * compare it to a checksum given by the user. If the checksums don't match, the driver will output
    * an error message. This is critical if you want to do forward or inverse kinematics based on the
@@ -158,6 +219,10 @@ class UrDriver
 
   /*!
    * \brief Constructs a new UrDriver object.
+   *
+   * \deprecated Initializing a UrDriver object with an argument list is deprecated. Please use UrDriver(const
+   *             UrDriverConfiguration& config) instead. This function will be removed in May 2027.
+   *
    * \param robot_ip IP-address under which the robot is reachable.
    * \param script_file URScript file that should be sent to the robot.
    * \param output_recipe_file Filename where the output recipe is stored in.
@@ -185,10 +250,8 @@ class UrDriver
    * \param force_mode_gain_scaling Scales the gain used when the robot is in force mode, range [0,2] (only e-series)
    */
   // Called sigB in tests
-  [[deprecated("Specifying the force mode damping factor and the force mode gain scaling factor at driver creation has "
-               "been deprecated. Force mode parameters should be specified with each activiation of force mode, and "
-               "can be set in the function call to start force mode. This function will be removed in May "
-               "2027.")]]
+  [[deprecated("Initializing a UrDriver object with an argument list is deprecated. Please use UrDriver(const "
+               "UrDriverConfiguration& config) instead. This function will be removed in May 2027.")]]
   UrDriver(const std::string& robot_ip, const std::string& script_file, const std::string& output_recipe_file,
            const std::string& input_recipe_file, std::function<void(bool)> handle_program_state, bool headless_mode,
            std::unique_ptr<ToolCommSetup> tool_comm_setup, const uint32_t reverse_port,
@@ -219,6 +282,10 @@ class UrDriver
 
   /*!
    * \brief Constructs a new UrDriver object.
+   *
+   * \deprecated Initializing a UrDriver object with an argument list is deprecated. Please use UrDriver(const
+   *             UrDriverConfiguration& config) instead. This function will be removed in May 2027.
+   *
    * \param robot_ip IP-address under which the robot is reachable.
    * \param script_file URScript file that should be sent to the robot.
    * \param output_recipe_file Filename where the output recipe is stored in.
@@ -281,6 +348,9 @@ class UrDriver
   /*!
    * \brief Constructs a new UrDriver object.
    *
+   * \deprecated Initializing a UrDriver object with an argument list is deprecated. Please use UrDriver(const
+   *             UrDriverConfiguration& config) instead. This function will be removed in May 2027.
+   *
    * \param robot_ip IP-address under which the robot is reachable.
    * \param script_file URScript file that should be sent to the robot.
    * \param output_recipe_file Filename where the output recipe is stored in.