97 lines
2.2 KiB
Plaintext
97 lines
2.2 KiB
Plaintext
= Rule Description
|
|
|
|
This document describes how `+rule.adoc+` and its dependencies should be structured.
|
|
|
|
== 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).
|