Comment Block Templates

Description

The following provides some templates for creating comment blocks in MicroV.

Single Line Template

All single line comments use the following form:

/// @brief <short description>

/** @breif <short description> */

Classes/Structs/Enum Templates

All object types use the following (remove fields that are not used, and all comment blocks should end with an empty ///, also change class to struct or enum as needed):

/// @class <namespace>::<name>
///
/// <!-- description -->
///   @brief <description>
///
/// <!-- notes -->
///   @note <optional, usually not needed>
///
/// <!-- template parameters -->
///   @tparam <template variable name> <description>
///

/**
 * @struct 
 *
 * <!-- description -->
 *   @brief 
 *   @include 
 *
 * <!-- notes -->
 *   @note 
 */

Function Templates

All functions use the following (remove fields that are not used, and all comment blocks should end with an empty ///)::

/// <!-- description -->
///   @brief <description>
///   @related <non member functions related to a specific class, usually not needed>
///
/// <!-- notes -->
///   @note <optional, usually not needed>
///
/// <!-- inputs/outputs -->
///   @tparam <template variable name> <description>
///   @param <variable name> <description>
///   @return <description>
///

/**
 * <!-- description -->
 *   @brief 
 *
 * <!-- notes -->
 *   @note 
 *
 * <!-- inputs/outputs -->
 *   @param 
 *   @return 
 */

VSCode Snippets

The following can be used with VSCode to automate the process of adding a function. Once created, as above, remove fields that are not used, but make sure the block ends with an empty ///

{
    "Function Comment": {
        "prefix": "comment_function",
        "body": [
            "/// <!-- description -->",
            "///   @brief $1",
            "///   @related $3",
            "///",
            "/// <!-- notes -->",
            "///   @note $4",
            "///",
            "/// <!-- inputs/outputs -->",
            "///   @tparam $7",
            "///   @param $8",
            "///   @return $9",
            "///",
        ],
        "description": "Function Comment"
    },
    "Class Comment": {
        "prefix": "comment_class",
        "body": [
            "/// @class $0",
            "///",
            "/// <!-- description -->",
            "///   @brief $1",
            "///",
            "/// <!-- notes -->",
            "///   @note $3",
            "///",
            "/// <!-- template parameters -->",
            "///   @tparam $4",
            "///"
        ],
        "description": "Class Comment"
    },
    "Struct Comment": {
        "prefix": "comment_struct",
        "body": [
            "/// @struct $0",
            "///",
            "/// <!-- description -->",
            "///   @brief $1",
            "///",
            "/// <!-- notes -->",
            "///   @note $3",
            "///",
            "/// <!-- template parameters -->",
            "///   @tparam $4",
            "///"
        ],
        "description": "Struct Comment"
    },
    "Enum Comment": {
        "prefix": "comment_enum",
        "body": [
            "/// @enum $0",
            "///",
            "/// <!-- description -->",
            "///   @brief $1",
            "///",
            "/// <!-- notes -->",
            "///   @note $3",
            "///"
        ],
        "description": "Enum Comment"
    }
}

And for c:

{
    "Function Comment": {
        "prefix": "comment_function",
        "body": [
            "/**",
            " * <!-- description -->",
            " *   @brief $1",
            " *",
            " * <!-- notes -->",
            " *   @note $4",
            " *",
            " * <!-- inputs/outputs -->",
            " *   @param $8",
            " *   @return $9",
            " */"
        ],
        "description": "Function Comment"
    },
    "Struct Comment": {
        "prefix": "comment_struct",
        "body": [
            "/**",
            " * @struct $0",
            " *",
            " * <!-- description -->",
            " *   @brief $1",
            " *   @include $2",
            " *",
            " * <!-- notes -->",
            " *   @note $3",
            " */"
        ],
        "description": "Struct Comment"
    }
    }
}