rspec/docs/description.adoc

= Rule Description

This document describes how `+rule.adoc+` and its dependencies should be structured.

See also the <<styling_guide.adoc#,Styling Guidelines>>.

== Sections

There should be no first level titles (`+= Title+`) in your adoc.

The following are the only allowed second level titles for H2:

include::./header_names/legacy_section_names.adoc[]

Most third-level titles (`+=== Title t3+`) are not checked, the only type of rule description for which some of these
titles are checked are the progressive education rules (see below).

== Types of rule description

The above list of allowed H2 sections is an absolute list and covers all the different types of rule descriptions that exist.
However, depending on the type of rule description, the expected order and allowed sections are not the same.
There are currently 3 types of rule descriptions, each having a specific structure.

=== 1. Standard

The standard rule description is the currently most widespread format. It includes all _Code Smells_, _Bugs_ and most _Vulnerabilities_.

This is the "classical" format that starts with a description of the rule, and is usually followed by code examples of bad and good practices,
with some links to resources at the end.

This format has the structure of the following section:

. Description (no title)
. Noncompliant Code Example
. Compliant Solution
. Exceptions
. See
. See Also

Note that most sections are optional, only the description is mandatory.

=== 2. Hotspot

Specific to the _Hotspot_ issue type, this format is mostly similar to the standard one,
with the addition of 2 new sections: `Ask Yourself Whether` and `Recommended Secure Coding Practices`. Additionally, the `Noncompliant Code Example`
section has been renamed into `Sensitive Code Example`: this is based on the fact that for  _Hotspots_ there is no certainty that what was raised
is an actual vulnerability.

The possible sections for this format are the following:

. Description (no title)
. Ask Yourself Whether
. Recommended Secure Coding Practices
. Sensitive Code Example
. Compliant Solution
. Exceptions
. See
. See Also

=== 3. Progressive Education

Finally, the last format is the one related to the effort done on Progressive Education.
This new format has a completely new structure, with additional subtitles and information,
so as to be as comprehensible as possible for the users.

This new structure is defined as follows:

... Short description (no title) ...

// This needs to be kept in sync with the [maps in the validation script](https://github.com/SonarSource/rspec/blob/3fb33d25c7bcfcde5a2426cb7177389cdcb6f5eb/rspec-tools/rspec_tools/validation/description.py#L32-L42).
* Why is this an issue?
** What is the potential impact?
* How to fix it
** Code examples
*** Noncompliant code example
*** Compliant solution
** How does this work?
** Pitfalls
** Going the extra mile
* How to fix it in {Framework Display Name}
** Code examples
*** Non-compliant examples
*** Compliant solution
** How does this work?
** Pitfalls
** Going the extra mile
* Resources (optional)
** Documentation
** Articles & blog posts
** Conference presentations
** Standards


Content of the section "_3. How to fix it_" (i.e. subsections 3.a, 3.b, 3.c and 3.d) may be repeated multiple times, as
each repetition will represent the specific _How to fix it_ section for a given framework.
For example:
....
== How to fix it

=== How to fix it in Spring
... Some generic text and code examples for Spring...

=== How does this work?
... Explanation about how the exploit works in Spring...

=== Pitfalls
... Generic and Spring-specific pitfalls to avoid when fixing the issue...

=== How to fix it in JSP
... Some generic text and code examples for JSP...

=== How does this work?
... Explanation about how the exploit works in JSP...

=== Pitfalls
... Generic and JSP-specific pitfalls to avoid when fixing the issue...
....

Ideally, by convention and for maintainability, each framework _How to fix it_ section will be defined in separate files.
Ex:
....
== How to fix it

 include::./how-to-fix-it/framework-1.adoc[]

 include::./how-to-fix-it/framework-2.adoc[]
....

Note that each framework-specific _How to fix it_ subsection must start with an H2 subtitle following the given format:
`How to fix it in (?:(?:an|a|the)\\s)?(.*)`.
This is important, as this format will be expected by the analyzers when loading the rule content to recognize the different subsections.
Furthermore, the display name of the framework has to match an allowed framework
display name, as defined in <<allowed_framework_names.adoc#,this allowed framework names file>>.

Finally, additional information regarding each of the sections and subsections present in the educational rule description
can be found https://docs.google.com/document/d/1caqBXTO1r7vftWrNXt_aNVe4rHcB5C6u6oKMBFjbzwo[in this document].

== Code Examples

Whenever possible, prefix your code blocks with `[source,language]`, in order to get syntax coloring.

....
[source,cpp]
----
int main(int argc, const char** argv) {
    return 0;
}
----
....

That is mandatory for the Noncompliant and Compliant code example sections, just recommended - at the moment - for other sections.

The language names accepted are usually the name we already use for the language folders in RSPEC. Exceptions are:

cfamily:: use `cpp`, `c`, or `objectivec`

plsql:: use `sql`

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.

== Parameters

Parameters should be listed in a subsection as follow:

....
=== Parameters

.name
****
_TYPE_

----
default value
----

Description of what the parameter does.
****

.name2
****
----
another default value
----
Description of what this second parameter does.
****

.name3
****
_TYPE_

Description of what this third parameter does.
****

.name4
****
Description of what this fourth parameter does.
****

....

The parameter name and the description are mandatory. The type and default value are not.

The parameter name with a `.` before will be the title of the block below marked by `****`.

We always use `----` around the default parameter to avoid having a special character confuse AsciiDoctor and to create a visual consistency for all parameters.

== Comment a rule

Comments and links that were created on Jira have been gathered in a `comments-and-links.adoc` file for each concerned rule. +
You can add a comment anywhere in a rule by adding the following lines in the `*.adoc` file:
[source]
----
\ifdef::env-github,rspecator-view[]
John Doe (9 Jun 2021, 15:49): my comment on the rule
\endif::env-github,rspecator-view[]
----
This way, your comment will only be visible in GitHub preview and on the Search Page (and will not be visible for the user).