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: philmd@redhat.com) Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) by groups.io with SMTP; Fri, 06 Sep 2019 01:01:00 -0700 Received: from mail-wr1-f72.google.com (mail-wr1-f72.google.com [209.85.221.72]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id C008D2D6A3E for ; Fri, 6 Sep 2019 08:00:59 +0000 (UTC) Received: by mail-wr1-f72.google.com with SMTP id j10so2183709wrb.16 for ; Fri, 06 Sep 2019 01:00:59 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:subject:to:cc:references:from:openpgp:message-id :date:user-agent:mime-version:in-reply-to:content-language :content-transfer-encoding; bh=cBYC+hzTZ5gpaPWFX/G8xuLbdp6Pn+t9NKDgZA6j43c=; b=cYwegQvxvBLwNSbeZ6k+xkdVrUAAXEmASosk5Dse+vh9Jv3JI4Avu12bj8OtKsATS0 GqG6hI2m6OBEwnpZzmQV0QvUz2JST1NaZPlDizfMtMo5TrXsqDPihwrbTBO7pDTj+Kqh /xatFjYPKDxZVXBFbH8YWOE5s2hCWWHn0grfRxNU4AEKsxbeBKrQDicKXVz56VgGOfEU 26zaQJxYKQiOJ1lky84drTTRleRJAgxvpFhoHLYbPhL+w6kvwFB2LUwJqP7R8bdaM1Py h6Eckdt/YUa25hRjOXVcpuYMBdOHgnpUvW23vAZlqmzS4Ytio8hn7J9b6F5pBOxN7t6x T0Tw== X-Gm-Message-State: APjAAAX9m62mnywe9a1x+ZqGlBAJa8LrERBSOd0x+rVY9V3rqflh7sIe 7Qpn0F9ZhUyumYegOPrZ+dx48QnucQhBQt6k9UpVq3MYg/TjcX0gZFjuNjNPGnFifjeyXi8+GTZ lXbtvVGiJNFpd2A== X-Received: by 2002:adf:8b13:: with SMTP id n19mr2710223wra.203.1567756858576; Fri, 06 Sep 2019 01:00:58 -0700 (PDT) X-Google-Smtp-Source: APXvYqxvZuOVYYVNuvkNM12LnGhYaQZD7nsl1JD5CM6vYS4wdNY8n6V42FioGbrEH27iJbnTwnuMIw== X-Received: by 2002:adf:8b13:: with SMTP id n19mr2710205wra.203.1567756858360; Fri, 06 Sep 2019 01:00:58 -0700 (PDT) Received: from [192.168.1.48] (251.red-88-10-102.dynamicip.rima-tde.net. [88.10.102.251]) by smtp.gmail.com with ESMTPSA id a130sm7833094wmf.48.2019.09.06.01.00.57 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Fri, 06 Sep 2019 01:00:57 -0700 (PDT) Subject: Re: [edk2-devel] [PATCH edk2-CCSS 2/3] comments: restrict and clarify applicability of "/*" comments To: devel@edk2.groups.io, lersek@redhat.com Cc: Andrew Fish , Leif Lindholm , Michael D Kinney , Rebecca Cran References: <20190905183820.10312-1-lersek@redhat.com> <20190905183820.10312-3-lersek@redhat.com> From: =?UTF-8?B?UGhpbGlwcGUgTWF0aGlldS1EYXVkw6k=?= Openpgp: id=89C1E78F601EE86C867495CBA2A3FD6EDEADC0DE; url=http://pgp.mit.edu/pks/lookup?op=get&search=0xA2A3FD6EDEADC0DE Message-ID: Date: Fri, 6 Sep 2019 10:00:56 +0200 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Thunderbird/60.7.0 MIME-Version: 1.0 In-Reply-To: <20190905183820.10312-3-lersek@redhat.com> Content-Type: text/plain; charset=utf-8 Content-Language: en-US Content-Transfer-Encoding: 7bit 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 > Cc: Leif Lindholm > Cc: Michael D Kinney > Cc: Rebecca Cran > Ref: https://bugzilla.tianocore.org/show_bug.cgi?id=607 > 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_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