search

AIDynamicAction / rcognita

rcognita is a flexibly configurable framework for agent-enviroment simulation with a menu of predictive and safe reinforcement learning controllers
MIT License
16 stars 7 forks source link

Inline RST documentation does not follow conventional practices. Info field lists should be utilized. #33

Open yaremenko8 opened 2 years ago

yaremenko8 commented 2 years ago

A great deal of code is currently documented in an unconventional fashion. To be more precise, there seems to be a tendency to use headings to describe attributes, parameters and returned values, as opposed using info field lists.

For instance consider the docstring for rcognita.controllers.ctrl_selector:

    Main interface for various controllers.
        Parameters
        ----------
        mode : : string
            Controller mode as acronym of the respective control method.
        Returns
        -------
        action : : array of shape ``[dim_input, ]``.
            Control action.

The conventional way to produce a docstring bearing such information would be:

    Main interface for various controllers.

    :param str mode: Controller mode as acronym of the respective control method.
    :return: Control action
    :rtype: array of shape ``[dim_input, ]``