diff --git a/rules/S6620/java/a.adoc b/rules/S6620/a.adoc similarity index 100% rename from rules/S6620/java/a.adoc rename to rules/S6620/a.adoc diff --git a/rules/S6620/java/b.adoc b/rules/S6620/b.adoc similarity index 100% rename from rules/S6620/java/b.adoc rename to rules/S6620/b.adoc diff --git a/rules/S6620/cfamily/metadata.json b/rules/S6620/cfamily/metadata.json new file mode 100644 index 00000000000..2c63c085104 --- /dev/null +++ b/rules/S6620/cfamily/metadata.json @@ -0,0 +1,2 @@ +{ +} diff --git a/rules/S6620/cfamily/rule.adoc b/rules/S6620/cfamily/rule.adoc new file mode 100644 index 00000000000..630e013c51a --- /dev/null +++ b/rules/S6620/cfamily/rule.adoc @@ -0,0 +1,2 @@ +include::../description.adoc[] + diff --git a/rules/S6620/description.adoc b/rules/S6620/description.adoc new file mode 100644 index 00000000000..e5ed8ead145 --- /dev/null +++ b/rules/S6620/description.adoc @@ -0,0 +1,192 @@ +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 two forms: `Embedded within a sentence`, in some cases as part of ``word``s, without spaces surrounding it. + +[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 diff --git a/rules/S6620/java/included1.adoc b/rules/S6620/included1.adoc similarity index 100% rename from rules/S6620/java/included1.adoc rename to rules/S6620/included1.adoc diff --git a/rules/S6620/java/included2.adoc b/rules/S6620/included2.adoc similarity index 100% rename from rules/S6620/java/included2.adoc rename to rules/S6620/included2.adoc diff --git a/rules/S6620/java/metadata.json b/rules/S6620/java/metadata.json index f6b97341698..2c63c085104 100644 --- a/rules/S6620/java/metadata.json +++ b/rules/S6620/java/metadata.json @@ -1,17 +1,2 @@ { - "title": "This is a rule showcasing which features avaibles in Asciidoc as available when writing a rule description", - "type": "CODE_SMELL", - "status": "ready", - "remediation": { - "func": "Constant\/Issue", - "constantCost": "5min" - }, - "tags": [ - ], - "defaultSeverity": "Major", - "ruleSpecification": "RSPEC-6620", - "sqKey": "S6620", - "scope": "All", - "defaultQualityProfiles": ["Sonar way"], - "quickfix": "unknown" } diff --git a/rules/S6620/java/rule.adoc b/rules/S6620/java/rule.adoc index e5ed8ead145..630e013c51a 100644 --- a/rules/S6620/java/rule.adoc +++ b/rules/S6620/java/rule.adoc @@ -1,192 +1,2 @@ -FIXME: add a description +include::../description.adoc[] -// 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 two forms: `Embedded within a sentence`, in some cases as part of ``word``s, without spaces surrounding it. - -[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 diff --git a/rules/S6620/metadata.json b/rules/S6620/metadata.json index 2c63c085104..607db148829 100644 --- a/rules/S6620/metadata.json +++ b/rules/S6620/metadata.json @@ -1,2 +1,23 @@ { + "title": "This is a rule showcasing which features avaibles in Asciidoc as available when writing a rule description", + "type": "CODE_SMELL", + "code": { + "impacts": { + "MAINTAINABILITY": "HIGH" + }, + "attribute": "LOGICAL" + }, + "status": "ready", + "remediation": { + "func": "Constant\/Issue", + "constantCost": "5min" + }, + "tags": [ + ], + "defaultSeverity": "Major", + "ruleSpecification": "RSPEC-6620", + "sqKey": "S6620", + "scope": "All", + "defaultQualityProfiles": ["Sonar way"], + "quickfix": "unknown" }