ishangsf/rspec
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add guidelines to format references to code elements

Browse Source
This commit is contained in:
Loïc Joly 2024-10-15 22:29:53 +02:00 committed by GitHub
parent 82b94b9a0b
commit 733ac96ca6
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 24 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
docs/description.adoc
View File

@ -271,6 +271,16 @@ 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
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
----
=== Diff view
Additionally, you can also use two attributes to let the products know your code examples should be highlighted with a diff view when possible

14
docs/styling_guide.adoc
View File

@ -109,3 +109,17 @@ Use it when referencing variable names, file names, tokens, and all kinds of spe
Write:: Compiling source file `src/generic_file.py` breaks an `assert` call in pytest framework.
Avoid:: Compiling source file "src/generic_file.py" breaks an `assert` call in `pytest` framework.
== Referencing elements from the code
When referencing elements from the code within a normal sentence, use the `backticks` (```) to format it. This includes variable names, function names, class names, and so on.
When referencing the same elements within a comment in a code block, surrpond it with double quotes.
[source,cpp]
----
int i = 0;
// Write
cout << noexcept(++i); // Noncompliant, "i" is not incremented -> Double quotes
// Avoid
cout << noexcept(++i); // Noncompliant, i is not incremented -> No quotes
cout << noexcept(++i); // Noncompliant, `i` is not incremented -> Backticks
----