Received: from list by lists.gnu.org with archive (Exim 4.71) id 1h9tA8-0002M9-4f for mharc-grub-devel@gnu.org; Fri, 29 Mar 2019 11:11:20 -0400 Received: from eggs.gnu.org ([209.51.188.92]:46986) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1h9tA5-0002Jz-Mi for grub-devel@gnu.org; Fri, 29 Mar 2019 11:11:18 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1h9tA4-0005JV-Kx for grub-devel@gnu.org; Fri, 29 Mar 2019 11:11:17 -0400 Received: from userp2130.oracle.com ([156.151.31.86]:34460) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1h9tA4-0005Gb-9n for grub-devel@gnu.org; Fri, 29 Mar 2019 11:11:16 -0400 Received: from pps.filterd (userp2130.oracle.com [127.0.0.1]) by userp2130.oracle.com (8.16.0.27/8.16.0.27) with SMTP id x2TF3oQR049444; Fri, 29 Mar 2019 15:11:14 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=from : to : cc : subject : date : message-id; s=corp-2018-07-02; bh=B4ECBSj92B9jQUifY5Jiq6VMdBY0bpfPZhrtgojS5Nk=; b=BZ1O3cQXezNXpInSgGP1E8zxBbQ8LsrCOd8T4dLLBtQwTQX+/pSiSoNoGceWKlXMLK7g af1bSbFmrMW7ixq67RC3rHDIyp+Wh44eL8eBfml+okZx/2O9iSZPYJbH+260NxMP7/vF +vzG6IS8c0VAkTAJQxEIZ1IPJfrjF0V7P4SDt57ubC08Re0HjOBRcHZ9QafS0F3veDMW j0ybHQnevLwlNWER7r4h7Gyud+EOwhzE9VHlJCTVJG3b9DFhlz1mv83lZtkcR5ocZ3A8 BAc5svxdYcRggP3rbGJFpN1esRlkfzLWn536uAbZXL90UVZY6GAlJA9ZaZ77xBf4+Dsj QQ== Received: from userv0022.oracle.com (userv0022.oracle.com [156.151.31.74]) by userp2130.oracle.com with ESMTP id 2re6g1n0hd-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Fri, 29 Mar 2019 15:11:13 +0000 Received: from userv0121.oracle.com (userv0121.oracle.com [156.151.31.72]) by userv0022.oracle.com (8.14.4/8.14.4) with ESMTP id x2TFBDaw031643 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Fri, 29 Mar 2019 15:11:13 GMT Received: from abhmp0016.oracle.com (abhmp0016.oracle.com [141.146.116.22]) by userv0121.oracle.com (8.14.4/8.13.8) with ESMTP id x2TFBDJu014898; Fri, 29 Mar 2019 15:11:13 GMT Received: from tomti.i.net-space.pl (/10.175.169.172) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Fri, 29 Mar 2019 08:11:12 -0700 From: Daniel Kiper To: grub-devel@gnu.org Cc: eric.snowberg@oracle.com, konrad.wilk@oracle.com, phcoder@gmail.com Subject: [PATCH] docs/grub-dev: Change comments rules Date: Fri, 29 Mar 2019 16:11:04 +0100 Message-Id: <20190329151104.8162-1-daniel.kiper@oracle.com> X-Mailer: git-send-email 2.11.0 X-Proofpoint-Virus-Version: vendor=nai engine=5900 definitions=9211 signatures=668685 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 priorityscore=1501 malwarescore=0 suspectscore=1 phishscore=0 bulkscore=0 spamscore=0 clxscore=1015 lowpriorityscore=0 mlxscore=0 impostorscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1810050000 definitions=main-1903290108 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x [generic] X-Received-From: 156.151.31.86 X-BeenThere: grub-devel@gnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: The development of GNU GRUB List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 29 Mar 2019 15:11:18 -0000 Current comments forms are annoying, so, some of them are disallowed starting from now. New rules are more flexible and mostly aligned with, e.g., Linux kernel comments rules. Signed-off-by: Daniel Kiper --- docs/grub-dev.texi | 43 +++++++++++++++++++++++++++++-------------- 1 file changed, 29 insertions(+), 14 deletions(-) diff --git a/docs/grub-dev.texi b/docs/grub-dev.texi index 53eb52c42..862a677e0 100644 --- a/docs/grub-dev.texi +++ b/docs/grub-dev.texi @@ -183,38 +183,44 @@ If a macro is global, its name must be prefixed with GRUB_ and must consist of o @section Comments All comments shall be C-style comments, of the form @samp{/* @dots{} */}. - -Comments shall be placed only on a line by themselves. They shall not be placed together with code, variable declarations, or other non-comment entities. A comment should be placed immediately preceding the entity it describes. +A comment can be placed immediately preceding the entity it describes or it +can be placed together with code, variable declarations, or other non-comment +entities. However, it is recommended to not mix various forms especially in +types/structs descriptions. Acceptable: @example -/* The page # that is the front buffer. */ +/* The page # that is the front buffer. */ int displayed_page; -/* The page # that is the back buffer. */ -int render_page; @end example -Unacceptable: @example -int displayed_page; /* The page # that is the front buffer. */ -int render_page; /* The page # that is the back buffer. */ +int render_page; /* The page # that is the back buffer. */ @end example @node Multi-Line Comments @section Multi-Line Comments -Comments spanning multiple lines shall be formatted with all lines after the first aligned with the first line. - -Asterisk characters should not be repeated a the start of each subsequent line. +Comments spanning multiple lines shall be formatted with all lines after the +first aligned with the first line. Asterisk characters should be repeated at +the start of each subsequent line. Acceptable: @example +/* + * This is a comment + * which spans multiple lines. + * It is long. + */ +@end example + +Unacceptable: +@example /* This is a comment which spans multiple lines. - It is long. */ + It is long. */ @end example -Unacceptable: @example /* * This is a comment @@ -222,7 +228,16 @@ Unacceptable: * It is long. */ @end example -The opening @samp{/*} and closing @samp{*/} should be placed together on a line with text. +@example +/* This is a comment + * which spans multiple lines. + * It is long. + */ +@end example + +In particular first unacceptable form makes comment difficult to distinguish +from the code itself. Especially if it contains the code snippets and/or is +long. So, its usage is disallowed. @node Finding your way around @chapter Finding your way around -- 2.11.0