Skip to content

Comment Block Templates

Jump to bottom
Rian Quinn edited this page Aug 6, 2021 · 5 revisions

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"
    }
    }
}

Copyright Templates

/// @copyright
/// Copyright (C) 2020 Assured Information Security, Inc.
///
/// @copyright
/// Permission is hereby granted, free of charge, to any person obtaining a copy
/// of this software and associated documentation files (the "Software"), to deal
/// in the Software without restriction, including without limitation the rights
/// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
/// copies of the Software, and to permit persons to whom the Software is
/// furnished to do so, subject to the following conditions:
///
/// @copyright
/// The above copyright notice and this permission notice shall be included in
/// all copies or substantial portions of the Software.
///
/// @copyright
/// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
/// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
/// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
/// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
/// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
/// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
/// SOFTWARE.
/**
 * @copyright
 * Copyright (C) 2020 Assured Information Security, Inc.
 *
 * @copyright
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * @copyright
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * @copyright
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */
#
# Copyright (C) 2020 Assured Information Security, Inc.
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in all
# copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
# SOFTWARE.
Clone this wiki locally