rspec/rules/S1103/pli/rule.adoc

== Why is this an issue?

Defining a nested single-line comment within a multi-line comment invites errors. It may lead a developer to wrongly think that the lines located after the single-line comment are not part of the comment.

=== Noncompliant code example

[source,pli]
----
/*
  This is a comment block, for which the ending tag was omitted
  It may be difficult to figure out that the following line of code is actually commented


variable = function_call();
/* variable contains the result, this is not allowed, as it is an attempt to create an inner comment */
----


ifdef::env-github,rspecator-view[]

'''
== Implementation Specification
(visible only on this page)

=== Message

Remove this misleading nested comment starting with character "/*"


'''
== Comments And Links
(visible only on this page)

include::../comments-and-links.adoc[]

endif::env-github,rspecator-view[]
migrate rule descriptions to new education format 2023-05-03 11:06:20 +02:00			`== Why is this an issue?`

Nightly update 2021-02-06 04:10:49 +00:00			`Defining a nested single-line comment within a multi-line comment invites errors. It may lead a developer to wrongly think that the lines located after the single-line comment are not part of the comment.`

migrate rule descriptions to new education format 2023-05-03 11:06:20 +02:00			`=== Noncompliant code example`
Nightly update 2021-02-06 04:10:49 +00:00
RULEAPI-661: Add syntax coloring 2022-02-04 17:28:24 +01:00			`[source,pli]`
Nightly update 2021-02-06 04:10:49 +00:00			`----`
			`/*`
			`This is a comment block, for which the ending tag was omitted`
			`It may be difficult to figure out that the following line of code is actually commented`


			`variable = function_call();`
			`/* variable contains the result, this is not allowed, as it is an attempt to create an inner comment */`
			`----`

Export comments and rspec-to-rspec links from jira 2021-06-02 20:44:38 +02:00
Fix the comment display: rule-id, timestamp, GH visibility, link direction 2021-06-03 09:05:38 +02:00			`ifdef::env-github,rspecator-view[]`
RULEAPI-666: Migrate the "List of parameters", "Highlighting" and "Message" fields from jira RSPEC (#346) 2021-09-20 15:38:42 +02:00
			`'''`
			`== Implementation Specification`
			`(visible only on this page)`

Inline adoc when include has no additional value (#1940) Inline adoc files when they are included exactly once. Also fix language tags because this inlining gives us better information on what language the code is written in. 2023-05-25 14:18:12 +02:00			`=== Message`

			`Remove this misleading nested comment starting with character "/*"`

RULEAPI-666: Migrate the "List of parameters", "Highlighting" and "Message" fields from jira RSPEC (#346) 2021-09-20 15:38:42 +02:00
RULEAPI-576: add a horizontal rule between rule description and comments 2021-06-08 15:52:13 +02:00			`'''`
Export comments and rspec-to-rspec links from jira 2021-06-02 20:44:38 +02:00			`== Comments And Links`
			`(visible only on this page)`

			`include::../comments-and-links.adoc[]`
Make sure that includes are always surrounded by empty lines (#2270) When an include is not surrounded by empty lines, its content is inlined on the same line as the adjacent content. That can lead to broken tags and other display issues. This PR fixes all such includes and introduces a validation step that forbids introducing the same problem again. 2023-06-22 10:38:01 +02:00
Fix the comment display: rule-id, timestamp, GH visibility, link direction 2021-06-03 09:05:38 +02:00			`endif::env-github,rspecator-view[]`