10BC0 CodeDocumentationStyle · CorsixTH/CorsixTH Wiki · GitHub
[go: up one dir, main page]
Skip to content

CodeDocumentationStyle

Jump to bottom Edit New page
Toby edited this page Mar 16, 2016 · 4 revisions

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)

Or with line comments:

--! One line description for the function f.

--! A longer description can be added here, wrapping multiple lines against the left border.
-- If the longer description has multiple lines, only the first line of the long description has the   
-- exclamation mark symbol (!). The other lines only need Lua's syntax for comment line (--).

--!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)

Reference documentation

First, install ''DoxyGen'' and ''LDocGen'' for C/C++ and Lua documentation respectively. Reference documentation can be generated with:

cd $repo_root
cmake .
make doc

Generated documentation can be found in $repo_root/doc

Add a custom footer
Add a custom sidebar

Clone this wiki locally
0