rspec/rules/S6620/description.adoc

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