Documentation

This section contains information about the Doxygen/Sphinx documentation format for the RAPIDSEA stack’s source and header files.

Header File Documentation Formats

Header

The `/*! ….. */` Doxygen comment style syntax must be used for description of the file.
Must follow the documentation format as shown in the example below,

Example:

File Name : rs_modbus_server.h

/*!
  \file       rs_modbus_server.h
  \brief      Modbus server Module
  \author     Embien RAPIDSEA Team
  \copyright  Embien Technologies India Pvt. Ltd.


  This file contains the APIs for using MODBUS server feature
*/

#ifndef H_RS_MODBUS_SERVER_H

 // Header file contents

Note

Here,
- file - Header File name
- brief - Brief description about the File.
- author - Embien RAPIDSEA Team.
- copyright - Embien Technologies India Pvt. Ltd.

Function Documentation

The `/*! ….. */` Doxygen comment style syntax must be used for description of the Function.
Must follow the documentation format as shown in the example below,

Example:

File Name : rs_modbus_server.h

/*! \fn          rs_handle_t rs_modbus_server_open(rs_modbus_server_info_t* ptr_instance, rs_modbus_server_config_t* ptr_config);
  \brief       Initializes the Modbus Server Channel for further communication
  \details     This function opens the underlying communication channel and prepares it for further communication with the master
  \param[in]   ptr_instance - Pointer to the Modbus server run time data
  \param[in]   ptr_config - Pointer to the Modbus server configuration information
  \return      Handle on success or negative error code
*/
rs_handle_t rs_modbus_server_open(rs_modbus_server_instance_t *ptr_instance, rs_modbus_server_config_t *ptr_config);

/*! \fn          void rs_modbus_server_process(rs_handle_t handle)
  \brief       Perform maintenance process on the Modbus Server instance
  \details     This function handles the Modbus server process functionality such as state machine etc. Must be called periodically
  \param[in]   handle - Handle to the Modbus server
  \return      Zero on success or error code on failure
*/
rs_ret_val_t rs_modbus_server_process(rs_handle_t handle);

Note

Here,
- fn - Function declarations
- brief - Brief description about the function definitions.
- details - Detail information about the function definitions.
- param[in/out] - Add the arguments details and type (Input or Output).
- return - Return value description and units.

Variable Documentation

This section contains examples of Doxygen comments for macros and structures.

Macros Documentation

The `//!` Doxygen comment style syntax must be used for macro descriptions.
Must follow the Doxygen documentation format as shown in the example below,

Example:

//! Modbus Communication Type (RTU, ASCII and TCP)
#define RS_MODBUS_COMM_TYPE_RTU              0U
#define RS_MODBUS_COMM_TYPE_ASCII            1U
#define RS_MODBUS_COMM_TYPE_TCP_IP           2U

Structure and Enums Documentation

The `//!` Doxygen comment style syntax must be used for structure and Enums description.
The `//!<` Doxygen comment style syntax must be used for structure and Enums member description.
Must follow the Doxygen documentation format as shown in the example below,

Example:

//! Contains information about server
typedef struct tag_rs_modbus_server_instance
{
   rs_modbus_server_config_t *ptr_config;    //!< Pointer to containing server configuration
   void *ptr_user_data;                                            //!< Pointer to user data by flint
   rs_handle_t transport_handle;             //!< Handle to the Modbus server interface (RTU/TCP)
   uint32_t data_len;                        //!< Data length of RX/TX packet
   uint8_t state;                            //!< Modbus server process state
   uint8_t run_state;                        //!< Modbus server run state
   uint8_t reconfigure;                      //!< Modbus server reconfiguration flag
   uint32_t comm_time_out;                   //!< Modbus server timeout for RX/TX
   uint8_t *ptr_buff;                        //!< Pointer to the buffer for RX/TX
   uint16_t buf_len;                         //!< Buffer length for RX/TX
   rs_handle_t modbus_handle;                //!< Handle to the Modbus server interface visible to the user
} rs_modbus_server_instance_t;

//! Contains information about list of module id's
typedef enum
{
   RS_MODULE_SPARKLET = 0,               //!< Sparklet module
   RS_AM_SPEEDOMETER,                    //!< Speedometer module
   RS_AM_ODOMETER,                       //!< Odometer module
   RS_AM_TRIPMETER,                      //!< Trip meter module
   RS_AM_TEMPERATURE,                    //!< Temperature module
} rs_module_id_t;

Source File Documentation Formats

Header

The `/*! ….. */` Doxygen comment style syntax must be used for description of the file.
Must follow the documentation format as shown in the example below,

Example:

File Name : rs_modbus_server.c

 /*!
   \file       rs_modbus_server.c
   \brief      Modbus Server Module
   \author     Embien RAPIDSEA Team
   \copyright  Embien Technologies India Pvt. Ltd.


 This file contains the APIs for handling modbus registers and server functionalities
*/

 #include <rs_lib.h>

  // file contents

Note

Here,
- file - File name
- brief - Brief description about the File.
- author - Embien RAPIDSEA Team.
- copyright - Embien Technologies India Pvt. Ltd.

Function Documentation

The `/*! ….. */` Doxygen comment style syntax must be used for description of the Function.
Must follow the documentation format as shown in the example below,

Example:

File Name : rs_modbus_server.c

/*! \fn          static rs_ret_val_t prepare_write_multiple_coils_response(rs_handle_t handle, rs_modbus_server_instance_t *ptr_info, uint8_t *ptr_server)
  \brief       Prepare response for write multiple coils
  \details     This function is used to prepare response for write multiple coils
  \param[in]   handle - Handle to the Modbus server
  \param[in]         ptr_info - Pointer to the server information
  \param[in]         ptr_server - Pointer to the buffer data
  \return      Return success for index or failure for error code
*/
static rs_ret_val_t prepare_write_multiple_coils_response(rs_handle_t handle, rs_modbus_server_instance_t *ptr_info, uint8_t *ptr_server)
{

  int32_t s32_ret_val;

  // Pointer validation
  if (ptr_mb_instance == NULL)
  {
    s32_ret_val = RS_ERR_NULL_POINTER;
  }

  return s32_ret_val;
}

rs_handle_t rs_modbus_server_open(rs_modbus_server_instance_t *ptr_instance, rs_modbus_server_config_t *ptr_config)
{
  rs_handle_t handle = -1;
  int32_t s32_ret_val = 0;
  rs_serial_config_t *ptr_serial_config = NULL;
  rs_socket_config_t *ptr_socket_config = NULL;

  // Pointer validation
  if (ptr_instance == NULL || ptr_config == NULL)
  {
    handle = RS_ERR_NULL_POINTER;
  }
  else
  {
    //Get the Handle

    ...
  }

  /* Get and Return
    the Handle
  */
  return handle;
}

Note

Static functions should only be defined in the source file, following Doxygen documentation guidelines—not all functions.
Comments inside functions must use either // (single-line) or /* … */ (multi-line) style for explaining the logic.

Variable & Macros Documentation

The `//!` Doxygen comment style syntax must be used for macro descriptions.
Must follow the Doxygen documentation format as shown in the example below,

Example:

//! Modbus Request Types
#define MODBUS_REQ_TYPE_READ_COILS                  0x1U
#define MODBUS_REQ_TYPE_READ_DISCRETE_INPUT         0x2U