This document describes how rule.adoc and its dependencies should be structured.
See also the Styling Guidelines.
There should be no first level titles (= Title) in your adoc.
The following are the only allowed second level titles for H2:
Third level titles are not checked.
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, orobjectivec - 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 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.
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:
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).