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::section_names.adoc[]

Third level titles are not checked.

== 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).