MTA-6448 Rules Development guide DITA modifications#349
Conversation
Signed-off-by: Prabha Kylasamiyer Sundara Rajan <pkylasam@pkylasam-thinkpadp16vgen1.bengluru.csb>
|
Caution Review failedThe pull request is closed. ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (2)
📝 WalkthroughWalkthroughThe PR removes and reorganizes documentation for YAML logical conditions. It deletes four complete documentation pages, removes the Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~22 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (3)
docs/topics/rules-development/yaml-chaining-java-provider.adoc (1)
10-10: Clarify "upper case" wording for precision.The phrasing "must be in upper case" is technically imprecise. The variable
Filepathsuses PascalCase (capitalized first letter), not "upper case" (which typically implies ALL CAPS likeFILEPATHS).Consider revising to: "the
Filepathsvariable must be capitalized" or "must use PascalCase" for technical accuracy.📝 Suggested rewording
-In the `java` provider, the `Filepaths` variable must be in upper case, for example: +In the `java` provider, the `Filepaths` variable must be capitalized, for example:🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/topics/rules-development/yaml-chaining-java-provider.adoc` at line 10, Update the wording that currently says "must be in upper case" for the `Filepaths` variable in the `java` provider: replace that phrase with a precise term such as "must be capitalized" or "must use PascalCase" (e.g., `Filepaths`) so it accurately describes the required naming convention for the variable `Filepaths` in the java provider documentation.docs/rules-development-guide/master.adoc (1)
35-36: Verify intended TOC impact of "Additional resources" section.The change from a level-2 section heading (
== Additional resources) to a block title (.Additional resources) with an explicit ID will remove "Additional resources" from the document's table of contents while still allowing it to be cross-referenced.If keeping "Additional resources" out of the TOC is intentional (treating it as supplementary content rather than a main section), this change is correct. However, if it should remain in the TOC for navigation, the original
== Additional resourcessyntax should be retained and combined with the explicit ID:[id="_additional-resources"] == Additional resourcesPlease confirm whether "Additional resources" should appear in the generated table of contents.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/rules-development-guide/master.adoc` around lines 35 - 36, The document changed the "Additional resources" heading from a level-2 section to a block title with an ID, which removes it from the generated TOC; if you want it to appear in the TOC restore the section syntax by replacing the block title `.Additional resources` with a level-2 heading and keep the explicit ID above it (i.e., use `[id="_additional-resources"]` followed by `== Additional resources`), otherwise leave the block title as-is if you intentionally want it omitted from the TOC.assemblies/rules-development-guide/assembly_logical-chaining-custom-variables.adoc (1)
21-21: Minor wording inconsistency: "aggregate or filter" versus "aggregate results".The sentence introduces "aggregate or filter conditions" as general capabilities, but then describes both
andandorconditions as being used to "aggregate results." The detailed topic files for both conditions also use "aggregate" terminology exclusively. Consider aligning the wording for consistency.For example, you could simplify to:
-* Logical conditions inform the provider how to handle more than one condition in a when block. You can aggregate or filter conditions using logical operations. The analyzer provides two basic logical conditions, `and` and `or`, which you can use to aggregate results of other conditions. +* Logical conditions inform the provider how to handle more than one condition in a when block. The analyzer provides two basic logical conditions, `and` and `or`, which you can use to aggregate results of other conditions using logical operations.Alternatively, if "filter" is a distinct capability, consider clarifying which conditions aggregate versus filter.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@assemblies/rules-development-guide/assembly_logical-chaining-custom-variables.adoc` at line 21, Update the wording so it's consistent: change "aggregate or filter conditions" to "aggregate conditions" (or explicitly state which operators filter) in the sentence describing Logical conditions inside the when block; specifically edit the sentence that mentions `and` and `or` to use "aggregate results" to match the `and` and `or` topics, or else clarify that "filter" is a different capability and which operators perform filtering.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In
`@assemblies/rules-development-guide/assembly_logical-chaining-custom-variables.adoc`:
- Line 21: Update the wording so it's consistent: change "aggregate or filter
conditions" to "aggregate conditions" (or explicitly state which operators
filter) in the sentence describing Logical conditions inside the when block;
specifically edit the sentence that mentions `and` and `or` to use "aggregate
results" to match the `and` and `or` topics, or else clarify that "filter" is a
different capability and which operators perform filtering.
In `@docs/rules-development-guide/master.adoc`:
- Around line 35-36: The document changed the "Additional resources" heading
from a level-2 section to a block title with an ID, which removes it from the
generated TOC; if you want it to appear in the TOC restore the section syntax by
replacing the block title `.Additional resources` with a level-2 heading and
keep the explicit ID above it (i.e., use `[id="_additional-resources"]` followed
by `== Additional resources`), otherwise leave the block title as-is if you
intentionally want it omitted from the TOC.
In `@docs/topics/rules-development/yaml-chaining-java-provider.adoc`:
- Line 10: Update the wording that currently says "must be in upper case" for
the `Filepaths` variable in the `java` provider: replace that phrase with a
precise term such as "must be capitalized" or "must use PascalCase" (e.g.,
`Filepaths`) so it accurately describes the required naming convention for the
variable `Filepaths` in the java provider documentation.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: b2e25a41-9701-4bae-b0d0-8173bb9028a9
📒 Files selected for processing (18)
assemblies/rules-development-guide/assembly_logical-chaining-custom-variables.adocassemblies/rules-development-guide/assembly_rule-rulesets.adocdocs/rules-development-guide/master.adocdocs/topics/rules-development/create-basic-yaml-rule-template.adocdocs/topics/rules-development/create-basic-yaml-ruleset-template.adocdocs/topics/rules-development/create-yaml-rule.adocdocs/topics/rules-development/mta-about-home-var.adocdocs/topics/rules-development/running-analysis-using-custom-yaml-rule.adocdocs/topics/rules-development/yaml-and-condition.adocdocs/topics/rules-development/yaml-builtin-provider.adocdocs/topics/rules-development/yaml-chaining-java-provider.adocdocs/topics/rules-development/yaml-dotnet-provider.adocdocs/topics/rules-development/yaml-go-provider.adocdocs/topics/rules-development/yaml-java-provider.adocdocs/topics/rules-development/yaml-logical-conditions.adocdocs/topics/rules-development/yaml-or-condition.adocdocs/topics/rules-development/yaml-rule-labels.adocdocs/topics/rules-development/yaml-rulesets.adoc
💤 Files with no reviewable changes (6)
- assemblies/rules-development-guide/assembly_rule-rulesets.adoc
- docs/topics/rules-development/create-basic-yaml-ruleset-template.adoc
- docs/topics/rules-development/running-analysis-using-custom-yaml-rule.adoc
- docs/topics/rules-development/yaml-logical-conditions.adoc
- docs/topics/rules-development/mta-about-home-var.adoc
- docs/topics/rules-development/create-yaml-rule.adoc
Signed-off-by: Prabha Kylasamiyer Sundara Rajan <pkylasam@pkylasam-thinkpadp16vgen1.bengluru.csb>
| You can create complex conditions in rules by using the following: | ||
|
|
||
| * Logical conditions inform the provider how to handle more than one condition in a when block. You can aggregate or filter conditions using logical operations. | ||
| * Logical conditions inform the provider how to handle more than one condition in a when block. The analyzer provides two basic logical conditions, `and` and `or`, which you can use to aggregate results of other conditions. |
There was a problem hiding this comment.
| * Logical conditions inform the provider how to handle more than one condition in a when block. The analyzer provides two basic logical conditions, `and` and `or`, which you can use to aggregate results of other conditions. | |
| * Logical conditions inform the provider how to handle more than one condition in a `when` block. The analyzer provides `and` and `or` basic logical conditions that you can use to aggregate results of other conditions. |
| ---- | ||
|
|
||
| .Example | ||
| For example: |
There was a problem hiding this comment.
This wording seems a bit redundant since you introduce these block as examples in the sentence above
| For example: |
There was a problem hiding this comment.
I removed the block .Example because that's been cited as a Block title issue in the DITA check. That's why I changed it to "For example:" which is just text.
|
|
||
| By using the `referenced` capability, the provider finds references in the source code. This capability takes three input parameters: `pattern`, `location`, and `annotated`. | ||
| + | ||
|
|
There was a problem hiding this comment.
The rendering fails in the preview. I think this is because of this one addition sign
| + | ||
| where: | ||
|
|
||
| + |
There was a problem hiding this comment.
Not needed before the description list
| + |
| `annotated` :: Checks for specific annotations and their elements, such as name and value, in the Java code by using a query. For example, the following query matches the `Bean` (URL = “http://www.example.com”) annotation in the method. | ||
|
|
||
| + | ||
|
|
| value: "http://www.example.com" | ||
| ---- | ||
| + | ||
|
|
| ---- | ||
|
|
||
| .Example | ||
| For example: |
There was a problem hiding this comment.
ditto (see above)
| For example: |
There was a problem hiding this comment.
We have to remove .Example. Though this format is allowed in modular templates that we have, it's flagged as an error in every DITA run. Thoughts?
| ---- | ||
|
|
||
| .Dependency label selector | ||
| Dependency label selector:: |
There was a problem hiding this comment.
there's a problem with rendering in this section. Probably because of the absence of addition signs here and there. Please, check the preview
| * `konveyor.io/include`: Overrides filter behavior for a rule irrespective of the label selector used. The value can either be `always` or `never`. If you specify `always`, the analyzer always filters-in this rule, while for `never`, the analyzer excludes this rule. | ||
|
|
||
| .Label selector | ||
| Label selector:: |
There was a problem hiding this comment.
there's a problem with rendering in this section. Probably because of the absence of addition signs here and there. Please, check the preview
mpershina
left a comment
mpershina
left a comment
There was a problem hiding this comment.
Some rendering issues are present; also, a couple of suggestions.
Signed-off-by: Prabha Kylasamiyer Sundara Rajan <pkylasam@pkylasam-thinkpadp16vgen1.bengluru.csb>
| * Type reference including classes, interfaces and structure types (struct). For example: | ||
|
|
||
| [subs="+quotes"] | ||
| [source, yaml] |
There was a problem hiding this comment.
I suppose the preview isn't updated since I can see the issue with the [subs="+quotes"] block rendering as plain text
|
|
||
| Labels are specified under the `labels` field as a list of strings in `key=val` format as follows: |
There was a problem hiding this comment.
Rendering issue, please, see the preview. Having an empty line between the description list item and its description might result in rendering problems
| Labels are specified under the `labels` field as a list of strings in `key=val` format as follows: | |
| Labels are specified under the `labels` field as a list of strings in `key=val` format as follows: |
2 participants
JIRA
Version
Preview
Files removed/unavailable in the repo:
Summary by CodeRabbit