From 3495f45e8a88b84296f93528d8cb45c7cb739639 Mon Sep 17 00:00:00 2001 From: svorenova Date: Thu, 22 Mar 2018 13:24:56 +0000 Subject: [PATCH 1/2] Update CODING_STANDARD.md --- CODING_STANDARD.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/CODING_STANDARD.md b/CODING_STANDARD.md index c5d67173e14..6d42e3a273f 100644 --- a/CODING_STANDARD.md +++ b/CODING_STANDARD.md @@ -66,8 +66,8 @@ Formatting is enforced using clang-format. For more information about this, see /// This sentence, until the first dot followed by whitespace, becomes /// the brief description. More detailed text follows. Feel free to /// break this into paragraphs to aid readability. - /// \param arg_name: This parameter doesn't need much description - /// \param [out] long_arg_name: This parameter is mutated by the function. + /// \param arg_name This parameter doesn't need much description + /// \param [out] long_arg_name This parameter is mutated by the function. /// Extra info about the parameter gets indented an extra two columns, /// like this. /// \return The return value is literally the value returned by the @@ -77,6 +77,7 @@ Formatting is enforced using clang-format. For more information about this, see - The priority of documentation is readability. Therefore, feel free to use Doxygen features, or to add whitespace for multi-paragraph comment blocks if necessary. +- Do not use colon after `\param` name, e.g., `\param arg_name ...` is ok while `\param arg_name: ...` should be avoided - A comment block should immediately precede the definition of the entity it documents, which will generally mean that it will live in the source file. This allows us to take advantage of the one definition rule. If each entity From 39e501fcb444f3c3fb795e40cbee3648b2db37eb Mon Sep 17 00:00:00 2001 From: svorenova Date: Fri, 23 Mar 2018 09:31:24 +0000 Subject: [PATCH 2/2] Update CODING_STANDARD.md --- CODING_STANDARD.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CODING_STANDARD.md b/CODING_STANDARD.md index 6d42e3a273f..2274df9314a 100644 --- a/CODING_STANDARD.md +++ b/CODING_STANDARD.md @@ -77,7 +77,7 @@ Formatting is enforced using clang-format. For more information about this, see - The priority of documentation is readability. Therefore, feel free to use Doxygen features, or to add whitespace for multi-paragraph comment blocks if necessary. -- Do not use colon after `\param` name, e.g., `\param arg_name ...` is ok while `\param arg_name: ...` should be avoided +- When describing parameters of functions, you may use a colon after the parameter name but if you choose to do so, do not add a space between the name and the colon as this will show in the generated documentation. For example, both `\param arg_name ...` and `\param arg_name: ...` are fine but `\param arg_name : ...` should be avoided. - A comment block should immediately precede the definition of the entity it documents, which will generally mean that it will live in the source file. This allows us to take advantage of the one definition rule. If each entity