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