[edk2-devel] [PATCH edk2-CCSS 2/3] comments: restrict and clarify applicability of "/*" comments

Laszlo Ersek posted 3 patches 29 weeks ago

[edk2-devel] [PATCH edk2-CCSS 2/3] comments: restrict and clarify applicability of "/*" comments

Posted by Laszlo Ersek 29 weeks ago
Section "6.2 Comments" seems to permit "/*" for multi-line comments in
general. That's incorrect; "/*" comments are permitted only for a subset
of multi-line comments (namely Doxygen-style file and function header
comment blocks). Update the rule accordingly.

Cc: Andrew Fish <afish@apple.com>
Cc: Leif Lindholm <leif.lindholm@linaro.org>
Cc: Michael D Kinney <michael.d.kinney@intel.com>
Cc: Rebecca Cran <rebecca@bsdio.com>
Ref: https://bugzilla.tianocore.org/show_bug.cgi?id=607
Signed-off-by: Laszlo Ersek <lersek@redhat.com>
---
 6_documenting_software/62_comments.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/6_documenting_software/62_comments.md b/6_documenting_software/62_comments.md
index ae04e008a1eb..5feb5cee2055 100644
--- a/6_documenting_software/62_comments.md
+++ b/6_documenting_software/62_comments.md
@@ -54,7 +54,7 @@ minimal familiarity with the code. Clarity is important, but one should also
 strive for terse and concise comments. One should be able to see both the
 comment, and the code being commented on, on the same screen.
 
-### 6.2.1 Only use C style, "/*", comments for multi-line comments and on the same line as pre-processor directives.
+### 6.2.1 Only use C style, "/*", comments on the same line as pre-processor directives, and in Doxygen-style file and function header comment blocks.
 
 Compile can vary in their support for use of `//` in preprocessor directives
 (e.g. `#define`). Note that the mixing of `/* ... */` and `//` is not handled
-- 
2.19.1.3.g30247aa5d201



-=-=-=-=-=-=-=-=-=-=-=-
Groups.io Links: You receive all messages sent to this group.

View/Reply Online (#46934): https://edk2.groups.io/g/devel/message/46934
Mute This Topic: https://groups.io/mt/33157543/1787277
Group Owner: devel+owner@edk2.groups.io
Unsubscribe: https://edk2.groups.io/g/devel/unsub  [importer@patchew.org]
-=-=-=-=-=-=-=-=-=-=-=-

Re: [edk2-devel] [PATCH edk2-CCSS 2/3] comments: restrict and clarify applicability of "/*" comments

Posted by Philippe Mathieu-Daudé 29 weeks ago
On 9/5/19 8:38 PM, Laszlo Ersek wrote:
> Section "6.2 Comments" seems to permit "/*" for multi-line comments in
> general. That's incorrect; "/*" comments are permitted only for a subset
> of multi-line comments (namely Doxygen-style file and function header
> comment blocks). Update the rule accordingly.
> 
> Cc: Andrew Fish <afish@apple.com>
> Cc: Leif Lindholm <leif.lindholm@linaro.org>
> Cc: Michael D Kinney <michael.d.kinney@intel.com>
> Cc: Rebecca Cran <rebecca@bsdio.com>
> Ref: https://bugzilla.tianocore.org/show_bug.cgi?id=607
> Signed-off-by: Laszlo Ersek <lersek@redhat.com>
> ---
>  6_documenting_software/62_comments.md | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/6_documenting_software/62_comments.md b/6_documenting_software/62_comments.md
> index ae04e008a1eb..5feb5cee2055 100644
> --- a/6_documenting_software/62_comments.md
> +++ b/6_documenting_software/62_comments.md
> @@ -54,7 +54,7 @@ minimal familiarity with the code. Clarity is important, but one should also
>  strive for terse and concise comments. One should be able to see both the
>  comment, and the code being commented on, on the same screen.
>  
> -### 6.2.1 Only use C style, "/*", comments for multi-line comments and on the same line as pre-processor directives.
> +### 6.2.1 Only use C style, "/*", comments on the same line as pre-processor directives, and in Doxygen-style file and function header comment blocks.
>  
>  Compile can vary in their support for use of `//` in preprocessor directives
>  (e.g. `#define`). Note that the mixing of `/* ... */` and `//` is not handled
> 

Reviewed-by: Philippe Mathieu-Daude <philmd@redhat.com>

-=-=-=-=-=-=-=-=-=-=-=-
Groups.io Links: You receive all messages sent to this group.

View/Reply Online (#46967): https://edk2.groups.io/g/devel/message/46967
Mute This Topic: https://groups.io/mt/33157543/1787277
Group Owner: devel+owner@edk2.groups.io
Unsubscribe: https://edk2.groups.io/g/devel/unsub  [importer@patchew.org]
-=-=-=-=-=-=-=-=-=-=-=-