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

["Philippe Mathieu-Daudé" <philmd@redhat.com>]

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>