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

[Philippe Mathieu-Daudé]

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 at apple.com>
> Cc: Leif Lindholm <leif.lindholm at linaro.org>
> Cc: Michael D Kinney <michael.d.kinney at intel.com>
> Cc: Rebecca Cran <rebecca at bsdio.com>
> Ref: https://bugzilla.tianocore.org/show_bug.cgi?id=607
> Signed-off-by: Laszlo Ersek <lersek at 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 at 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/1813853
Group Owner: devel+owner at edk2.groups.io
Unsubscribe: https://edk2.groups.io/g/devel/unsub  [edk2-devel-archive at redhat.com]
-=-=-=-=-=-=-=-=-=-=-=-