From mboxrd@z Thu Jan 1 00:00:00 1970 Authentication-Results: mx.groups.io; dkim=missing; spf=pass (domain: redhat.com, ip: 209.132.183.28, mailfrom: lersek@redhat.com) Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) by groups.io with SMTP; Thu, 05 Sep 2019 11:38:27 -0700 Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id E16CBC04D312; Thu, 5 Sep 2019 18:38:26 +0000 (UTC) Received: from lacos-laptop-7.usersys.redhat.com (ovpn-116-133.ams2.redhat.com [10.36.116.133]) by smtp.corp.redhat.com (Postfix) with ESMTP id 8CB245D6A3; Thu, 5 Sep 2019 18:38:25 +0000 (UTC) From: "Laszlo Ersek" To: edk2-devel-groups-io Cc: Andrew Fish , Leif Lindholm , Michael D Kinney , Rebecca Cran Subject: [PATCH edk2-CCSS 2/3] comments: restrict and clarify applicability of "/*" comments Date: Thu, 5 Sep 2019 20:38:19 +0200 Message-Id: <20190905183820.10312-3-lersek@redhat.com> In-Reply-To: <20190905183820.10312-1-lersek@redhat.com> References: <20190905183820.10312-1-lersek@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.31]); Thu, 05 Sep 2019 18:38:26 +0000 (UTC) Content-Transfer-Encoding: quoted-printable 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 Cc: Leif Lindholm Cc: Michael D Kinney Cc: Rebecca Cran Ref: https://bugzilla.tianocore.org/show_bug.cgi?id=3D607 Signed-off-by: Laszlo Ersek --- 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_softwa= re/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 th= e comment, and the code being commented on, on the same screen. =20 -### 6.2.1 Only use C style, "/*", comments for multi-line comments and o= n the same line as pre-processor directives. +### 6.2.1 Only use C style, "/*", comments on the same line as pre-proce= ssor directives, and in Doxygen-style file and function header comment bl= ocks. =20 Compile can vary in their support for use of `//` in preprocessor direct= ives (e.g. `#define`). Note that the mixing of `/* ... */` and `//` is not ha= ndled --=20 2.19.1.3.g30247aa5d201