Code Documentation - AD-EYE/AD-EYE_Core GitHub Wiki

Documentating the code

The documentation tool used is doxygen.

C++ code

To document the source files tags need to be used in the comments

   /*!
    * \brief
    * \param
    * \return
    * \details 
    * \todo
   */

A class or function should always contain at least the tags brief, param and return (if the function is not a void).

See an example here: https://gits-15.sys.kth.se/AD-EYE/AD-EYE_Core/blob/dev/AD-EYE/ROS_Packages/src/AD-EYE/src/experimentC.cpp#L40

       /*!
        * \brief Constructor
        * \param nh A reference to the ros::NodeHandle initialized in the main function.
        * \details Initializes the node and its components such the as subscriber /current_velocity.
        */
        ExperimentC(ros::NodeHandle nh): ExperimentRecording(nh), nh_(nh), point_cloud_to_occupancy_grid_(nh, true), rate_(20)
        {
            ...
        }

Python Code

Refer to this link: https://www.doxygen.nl/manual/docblocks.html#pythonblocks As for C++, a class or function should always contain at least the tags brief, param and return.

See an example here: https://gits-15.sys.kth.se/AD-EYE/AD-EYE_Core/blob/dev/AD-EYE/ROS_Packages/src/AD-EYE/src/base_map_goal_loop_sender.py#L31

    ##A method for publishing new goals.
    #@param self The object pointer
    #@param index The index (Integer) for the new goal in the list of goals
    def publishNewGoal(self,index):   
        ...

JavaScript code

Use the same template as C++

Generating the documentation

To generate the documenttion navigate to AD-EYE_Core/Documentation and run the command doxygen Doxyfile.

A folder called html should appear. Open index.html to see the documentation.

Setting up your environment

To install doxygen follow instructions, run sudo apt install doxygen on a terminal

The following dependencies might be needed:

sudo apt-get install flex
sudo apt-get install bison

The variable SOURCE_BROWSER allows to show the line number and file where the elements are define if set to YES.

References

-   https://www.doxygen.nl/manual/docblocks.html#pythonblocks
-   https://realpython.com/documenting-python-code/
-   https://github.com/Feneric/doxypypy
-   https://www.doxygen.nl/manual/install.html
-   https://numpydoc.readthedocs.io/en/latest/format.html
-   https://www.youtube.com/watch?v=YxmdCxX9dMk
-   https://www.youtube.com/watch?v=TtRn3HsOm1s