From 3837a175d3e9282bc31e91e70030bea115e30eba Mon Sep 17 00:00:00 2001 From: Antonio Aversa Date: Mon, 21 Oct 2024 10:27:29 +0200 Subject: [PATCH] Convention: use colon as separator in comments within code blocks (#4425) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Loïc Joly --- docs/description.adoc | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/description.adoc b/docs/description.adoc index b0da5435c9..4e91c5ba93 100644 --- a/docs/description.adoc +++ b/docs/description.adoc @@ -271,14 +271,22 @@ tsql:: use `sql` In case no language is appropriate for a code block (for example shared examples between multiple languages), you can use `text` as the language. -=== References within code blocks +=== Comments within code blocks + +Colon (`:`) should be used as separator between `Noncompliant`/`Compliant` comments and the text explanation that follows, if any. + +[source,cpp] +---- +int X = 2; // Noncompliant: variable should be in lowercase +---- + When referencing a name within a comment in a code example, use double quotes to make it clear it refers to an existing element in the code. [source,cpp] ---- int i = 0; -cout << noexcept(++i); // Noncompliant, "i" is not incremented +cout << noexcept(++i); // Noncompliant: "i" is not incremented ---- === Diff view