195 lines
4.3 KiB
Plaintext
195 lines
4.3 KiB
Plaintext
FIXME: add a description
|
|
|
|
// If you want to factorize the description uncomment the following line and create the file.
|
|
//include::../description.adoc[]
|
|
|
|
== Why is this an issue?
|
|
|
|
This rule is not really a rule, but a demonstration of the features from Asciidoc that can appear in a rule description.
|
|
|
|
=== All titles should be in sequence
|
|
|
|
No title 3 directly below title 1
|
|
|
|
==== Titles
|
|
|
|
There can be 4 different levels of titles, as demonstrated in this rule, usually with standard text.
|
|
|
|
==== Character format
|
|
|
|
It is not uncommon to have text in *bold*, _italic_, *_both_*. Less common are ^exponents^ and ~indices~.
|
|
|
|
We don't directly use highlighting, but use a specific form of it to [.underline]#underline# and [.line-through]#strikethrough#.
|
|
|
|
==== Source code
|
|
|
|
Code appears in `embedded within a sentence`, in some cases as part of ``word``s, without spaces surrounding it. Embedded code can also be an https://en.wikipedia.org/wiki/Hyperlink[`hyperlink`].
|
|
|
|
|
|
It can also appear as a separate block:
|
|
[source,csharp]
|
|
----
|
|
private void OtherSourceCode()
|
|
{
|
|
// We usually indicate what language is used for the code
|
|
}
|
|
----
|
|
|
|
----
|
|
But not always
|
|
----
|
|
|
|
[source,cpp]
|
|
----
|
|
private void YetAnotherSourceCode()
|
|
{
|
|
// One rule may contain several languages
|
|
}
|
|
----
|
|
|
|
[source,javascript,diff-id=1,diff-type=noncompliant]
|
|
----
|
|
// And the code can contain information
|
|
----
|
|
[source,javascript,diff-id=1,diff-type=compliant]
|
|
----
|
|
// And the code can contain diff information
|
|
----
|
|
|
|
Diff-views are documented https://github.com/SonarSource/rspec/blob/master/docs/description.adoc#diff-view[here].
|
|
|
|
[source,txt,diff-id=2,diff-type=noncompliant]
|
|
----
|
|
When using diff-views, there should be one noncompliant example.
|
|
----
|
|
|
|
[source,txt,diff-id=2,diff-type=compliant]
|
|
----
|
|
When using diff-views, there should be at least one compliant solution.
|
|
However, the diff-view feature was first designed to have only one compliant solution.
|
|
----
|
|
|
|
[source,txt,diff-id=2,diff-type=compliant]
|
|
----
|
|
When using diff-views,
|
|
Be mindful that providing more than one compliant solution
|
|
is "supported" but may completely disable the diff highlighting.
|
|
----
|
|
|
|
This limitation is discussed https://discuss.sonarsource.com/t/support-for-multiple-compliant-code-snippets-in-the-rspec-code-diffs/14644[here].
|
|
|
|
----
|
|
// We have cases where we are missing the [source,language] attributes
|
|
// TODO: Maybe we should detect and prevent this
|
|
----
|
|
|
|
==== Lists
|
|
|
|
There can be bullet lists:
|
|
|
|
* With
|
|
* three
|
|
** An sublists
|
|
** Up to
|
|
*** Three nested levels
|
|
*** But no more
|
|
* bullets
|
|
|
|
Or numbered lists:
|
|
|
|
. A list
|
|
. with numbers
|
|
.. And also possible sublists
|
|
.. with more items
|
|
|
|
|
|
==== Admonitions
|
|
|
|
They are not supported.
|
|
|
|
*Warning*: They are simulated with manual layout.
|
|
|
|
==== Links
|
|
|
|
There are links in the text, see https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#links for the various ways they can appear. Of course, the link can have https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#links[another text].
|
|
|
|
We can also link to other rules, such as S100. We cannot specify which language is the target of this link, it is always the same as the current RSPEC language.
|
|
|
|
==== Tables
|
|
|
|
[frame=all]
|
|
[cols="^1,<1, 2a"]
|
|
|===
|
|
|Title|What we use | Details
|
|
|
|
| Tables | A simple table |
|
|
| Alignment | Can differ between cols |
|
|
| Header | The first line is often a header |
|
|
| Strong s| A cell can be put in bold |
|
|
| Tables | A table | Nested asciidoc, with, for instance:
|
|
|
|
|
|
* Nested
|
|
* lists
|
|
|
|
See for instance S5131
|
|
| Merged cells | They are not supported |
|
|
| Borders | Most often all around |
|
|
| Nested tables | They are not supported |
|
|
|===
|
|
|
|
==== Includes
|
|
|
|
It is possible to include other files.
|
|
|
|
include::included1.adoc[]
|
|
|
|
Sometimes, the content of the included files can vary, with the use of a variable.
|
|
|
|
:var: variable text
|
|
|
|
include::included2.adoc[]
|
|
|
|
Which file is included can also depend on a variable:
|
|
|
|
:inc: a.adoc
|
|
|
|
include::{inc}[]
|
|
|
|
:inc: b.adoc
|
|
|
|
include::{inc}[]
|
|
|
|
|
|
== How to fix it
|
|
|
|
=== Code examples
|
|
|
|
==== Noncompliant code example
|
|
|
|
[source,text,diff-id=3,diff-type=noncompliant]
|
|
----
|
|
FIXME
|
|
----
|
|
|
|
==== Compliant solution
|
|
|
|
[source,text,diff-id=3,diff-type=compliant]
|
|
----
|
|
FIXME
|
|
----
|
|
|
|
//=== How does this work?
|
|
|
|
//=== Pitfalls
|
|
|
|
//=== Going the extra mile
|
|
|
|
|
|
//== Resources
|
|
//=== Documentation
|
|
//=== Articles & blog posts
|
|
//=== Conference presentations
|
|
//=== Standards
|
|
//=== Benchmarks
|