From patchwork Mon Jun 11 14:17:16 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 138244 Delivered-To: patches@linaro.org Received: by 2002:a2e:970d:0:0:0:0:0 with SMTP id r13-v6csp4115276lji; Mon, 11 Jun 2018 07:17:19 -0700 (PDT) X-Google-Smtp-Source: ADUXVKIIxLOxjQJmX2GDnb7Ol2NOBi6FKIawlTVDtNYWjpq2DAjRBAG5BPRCymfDPFKiIgP+deXd X-Received: by 2002:adf:ab10:: with SMTP id q16-v6mr12819561wrc.239.1528726639113; Mon, 11 Jun 2018 07:17:19 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1528726639; cv=none; d=google.com; s=arc-20160816; b=MunomhHLtaP4rGBUMxVIpxYNZdcVhimGDmNEv/vGjdWQYZHmSe5rN7ndJ1Aw7tuoJS FPEmZ8OUf3c06tOYYeQE5q8K8RCHMJXYFHAQ5zYfBIrjq5vD5kSqK9DaflC0pVOprBdc hZSpjMIB7xv+xRSUd4bvFALf1kt9dLh3cyLunpySSzEnS9c7YvrPqYEMphExnLvjbfUh H9bUlSzn0Ycjafjv1yYbASdAUeSPoN8FXiO2iQk9khwHIKjktNne8DufWqVzI6jJDQHx vr6CjA2mZxZDY8IAbZQBdukmiypWFL41SPWm1DUeX7RS7FXlAL7P5piKrnUWnkRq8KAa dhFQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=message-id:date:subject:cc:to:from:arc-authentication-results; bh=akjoAv8kNIHqCsLRLrDmHvbx4gHhKHK+j5QnhlLX0GE=; b=KnCmmH6lxc/8vyQE4D8d7zfbFsN8zHzEyGXHOd+rYqaOdw93uY2hyQIZsQ4BiJHE1d jLAW+KxZbJOOeXuT8jWwZZ0yhkh72Ro22JVSzQvjPFPfWUwRC+mDzDmxnB2xSw1ULBuF qvTSOMiJIuPQQ2mdEb0etAwPPGosvIZpUCjAFLNMDmpbGR+LP/UTClY9/X+obzM32SA3 4UvtBluNmAXVv1oS/W5zaqWxNrfYW0pclnAWGsugLKxGxGBJ/9T489DrTan4TYig187z S89JNcVseT73OyVgwoVMgGUKAKJ/FDhtLJDjHlxAF5SVajkAFuFn2HW7LpsOL2xn3jSk pcSg== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: best guess record for domain of pm215@archaic.org.uk designates 2001:8b0:1d0::2 as permitted sender) smtp.mailfrom=pm215@archaic.org.uk; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from orth.archaic.org.uk (orth.archaic.org.uk. [2001:8b0:1d0::2]) by mx.google.com with ESMTPS id n203-v6si6063830wmf.120.2018.06.11.07.17.18 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Mon, 11 Jun 2018 07:17:19 -0700 (PDT) Received-SPF: pass (google.com: best guess record for domain of pm215@archaic.org.uk designates 2001:8b0:1d0::2 as permitted sender) client-ip=2001:8b0:1d0::2; Authentication-Results: mx.google.com; spf=pass (google.com: best guess record for domain of pm215@archaic.org.uk designates 2001:8b0:1d0::2 as permitted sender) smtp.mailfrom=pm215@archaic.org.uk; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from pm215 by orth.archaic.org.uk with local (Exim 4.89) (envelope-from ) id 1fSNdF-00078H-BM; Mon, 11 Jun 2018 15:17:17 +0100 From: Peter Maydell To: qemu-devel@nongnu.org, qemu-trivial@nongnu.org Cc: patches@linaro.org, Richard Henderson , John Snow , =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Alex Williamson , Thomas Huth , Cornelia Huck , Markus Armbruster , Stefan Hajnoczi , Kevin Wolf Subject: [PATCH v2] CODING_STYLE: Define our preferred form for multiline comments Date: Mon, 11 Jun 2018 15:17:16 +0100 Message-Id: <20180611141716.3813-1-peter.maydell@linaro.org> X-Mailer: git-send-email 2.17.1 The codebase has a bit of a mix of different multiline comment styles. State a preference for the Linux kernel style: /* * Star on the left for each line. * Leading slash-star and trailing star-slash * each go on a line of their own. */ Signed-off-by: Peter Maydell --- This is not my personal favourite, but seemed to be the closest we had to consensus in the mail thread for v1; I can live with it in order to avoid getting patches which use the styles I like even less :-) --- CODING_STYLE | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) -- 2.17.1 Reviewed-by: Eric Blake Reviewed-by: Cornelia Huck Reviewed-by: Markus Armbruster Reviewed-by: Alex Williamson Reviewed-by: Thomas Huth Reviewed-by: John Snow Reviewed-by: Stefan Hajnoczi diff --git a/CODING_STYLE b/CODING_STYLE index 12ba58ee293..2d84f5f26d1 100644 --- a/CODING_STYLE +++ b/CODING_STYLE @@ -124,6 +124,23 @@ We use traditional C-style /* */ comments and avoid // comments. Rationale: The // form is valid in C99, so this is purely a matter of consistency of style. The checkpatch script will warn you about this. +Multiline comments blocks should have a row of stars on the left, +and the initial /* and terminating */ both on their own lines: + /* + * like + * this + */ +This is the same format required by the Linux kernel coding style. + +(Some of the existing comments in the codebase use the GNU Coding +Standards form which does not have stars on the left, or other +variations; avoid these when writing new comments, but don't worry +about converting to the preferred form unless you're editing that +comment anyway.) + +Rationale: Consistency, and ease of visually picking out a multiline +comment from the surrounding code. + 8. trace-events style 8.1 0x prefix