# Documentation Format
###### tags: `electrical_system` `NTURT`

## General comment

:::info
Start with two slash and a spece, with all lower case letter without period in the end.
:::

Ex. (C++)

// some comments
int variable_name;

## Doxygen

### Documentation session

:::info
Doxygen documentation sentence should start with a capital letter and ends with a period as a complete sentence.
:::

for multiple line documentation block:

/**
 * @author My name (my.email@com)
 * @brief Brief explanation.
 * 
 * Detailed explanation.
 */
class ClassName{};

for single line documentation

/// @brief Brief explanation.
int variable_name;

### How to document

:::info
Doxygen documentation should all only be in header files (hpp) in `include` directory, not in source files.
:::

### What should be documented

:::info

1. File documentation
2. Class/struct documentation
3. Variables/functions in header files

:::

Ex. (C++)

/**
 * @file header.hpp
 * @author Your name (my.email@com)
 * @brief Brief explanation of the file.
 */

#ifndef HEADER_HPP
#define HEADER_HPP

/**
 * @author Your name
 * @brief Brief explanation of the class.
 */
class SomeClass {
    public:
        /**
         * @brief Brief explanation of the function.
         * @param[in] _argument Brief explanation of the argument.
         * @return Brief explanation of the return.
         */
        int do_something(int _argument);
    
    private:
        /// @brief Brief explanation of the variable.
        int variable_;
}

### How to generate dyxygen output

#### Doxyfile

In Doxyfile (config file for doxygen), plaese change to the following settings:

...

PROJECT_NAME = "NAME_OF_THE_PROJECT"

PROJECT_NUMBER = "CURRENT_VERSION"

PROJECT_BRIEF = "BRIEF_OF_THE_PROJECT"

PROJECT_LOGO = "doc/NTU_Racing_Logo.png"

OUTPUT_DIRECTORY = "doxygen"

...

INPUT = "include" "README.md" "software_development_log.md"

...

USE_MATHJAX = YES

...

EXTRACT_PRIVATE = YES

...

USE_MDFILE_AS_MAINPAGE = "README.md"

...

:::info

Note: The logo for ntu racing can be found at here: [NTU_Racing_Logo](https://drive.google.com/file/d/1ZWAv9gL6xUT7SqnzocaX3FoD65A2lTtD/view?usp=sharing).

:::

## README

:::info
A README file should incorporate the following aspects of the program:
1. Usage
2. Functionality
:::