CodeDocumentationStyle

Code documentation style

To unify the comments that describe the functions, the following style is suggested.

Style for documenting Lua code

You can either use a block comment or line comments. With a block comment:

--[\[ One line description for the function f.

! Other description lines can be added here, wrapping multiple lines

against the left border.

!param name (type) The description of the parameter. Also mention special values with their meaning.

...

!return (type if possible) Description of the return value.

]]

function f(name)

(remove the \ character in the opening comment bracket, it's needed to make the wiki happy)

Or with line comments:

--! One line description for the function f.

--! Other description lines can be added here, wrapping multiple lines against the left border.

--!param name (type) The description of the parameter. Also mention special values with their meaning.

--!...

--!return (type if possible) Description of the return value.

function f(name)

Style for documenting C++ code

    //! One line description of the function f.

    /*!

        @param name Description of the parameter. Note that type of the parameter

          is not needed. Also mention special values with their meaning.

        ...

        @return Description of the return value.

    */

    int f(int name)