Skip to content

Commit 52b1deb

Browse files
d-biehld-biehl
committed
docs: add diagnostics modifiers section to reference documentation
1 parent bfc6801 commit 52b1deb

File tree

2 files changed

+293
-1
lines changed

2 files changed

+293
-1
lines changed

‎docs/03_reference/diagnostics-modifiers.md‎

Lines changed: 290 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,290 @@
1+
# Controlling Diagnostics with Modifiers
2+
3+
RobotCode offers advanced static analysis for Robot Framework files. With **diagnostics modifiers** you can control directly in your Robot code which diagnostic messages (lint / analysis errors, warnings, hints) are shown and with what severity.
4+
5+
This allows you to, for example:
6+
7+
- hide specific rules for individual lines, blocks or files,
8+
- adjust the severity of individual messages (hint → warning → error),
9+
- temporarily disable diagnostics completely and re-enable them later.
10+
11+
12+
## Basic Concept
13+
14+
RobotCode interprets special comments with the prefix `# robotcode:` as **diagnostics modifiers**.
15+
16+
General form:
17+
18+
```robot
19+
# robotcode: <action>[code1,code2,...] [<action>[code1,code2,...]]...
20+
```
21+
22+
- `action` is one of the predefined actions (see below).
23+
- `code` are the diagnostic codes you want to influence (for example `variable-not-found`, `keyword-not-found`, `MultipleKeywords`). If omitted, the action applies to all diagnostics.
24+
- You can chain multiple `<action>[...]` segments in the same comment; they are applied in the order written. If the same code appears more than once on the same line, the later action wins.
25+
26+
### Available Actions
27+
28+
- `ignore`: Ignore the given diagnostic codes completely (they will not be reported at all).
29+
- `hint`: Treat the given codes as hints (lowest severity, usually rendered as faded or informational markers).
30+
- `information` / `info`: Treat the given codes as informational messages (above hint, below warning).
31+
- `warning` / `warn`: Treat the given codes as warnings (visible but not failing).
32+
- `error`: Treat the given codes as errors (highest severity, typically used for CI or "problems" views).
33+
- `reset`: Reset the given codes to their default level as defined by the underlying analyzer and any global configuration.
34+
- `ignore` without list: Ignore **all** diagnostic messages in the affected scope.
35+
- `reset` without list: Reset **all** diagnostic messages to their default; any previous `ignore`, `hint`, `information`, `warning` or `error` modifiers in scope are cleared.
36+
37+
Additional rules:
38+
39+
- Codes are matched case-insensitively and normalized internally, so `VariableNotFound` and `variable-not-found` are treated the same.
40+
- Action names are also case-insensitive; `warn` = `warning`, `info` = `information`.
41+
- In global configuration (for example `robot.toml`) you can use `"*"` as a wildcard to match all remaining diagnostics (for example `hint = ["*"]`).
42+
- Inline `# robotcode:` modifiers on a specific line always override global configuration from `robot.toml` or CLI settings.
43+
- If several modifiers affect the same line and code, the nearest one wins: inline (end-of-line) > indented block > top-level file comment > global/CLI settings. Within one comment the rightmost action for the same code wins.
44+
45+
### Where do the diagnostic codes come from?
46+
47+
- Every diagnostic emitted by RobotCode carries a `code` field (LSP `Diagnostic.code`). That value is exactly what you put into `ignore[...]`, `warn[...]`, etc.
48+
- Core analyzers define their codes in `robotcode.robot.diagnostics.errors.Error` (for example `VariableNotFound`, `KeywordNotFound`, `MultipleKeywords`).
49+
- The simplest way to read the code is in your editor’s Problems/Diagnostics view or in the CLI output of `robotcode analyze`, where the code appears in brackets before the message (e.g. `[W] KeywordNotFound: ...`).
50+
- Custom analyzer plugins may emit additional codes; you handle them the same way via modifiers.
51+
52+
Common codes (core analyzer)
53+
54+
| Code | Meaning (short) |
55+
| ---------------------- | --------------------------------------------- |
56+
| VariableNotFound | Variable reference could not be resolved. |
57+
| KeywordNotFound | Keyword could not be resolved. |
58+
| MultipleKeywords | Call matches multiple keywords (ambiguous). |
59+
| DeprecatedKeyword | Called keyword is marked deprecated. |
60+
| PossibleCircularImport | Potential circular resource/variables import. |
61+
62+
Example CLI output (showing `code` before the message)
63+
64+
```bash
65+
$ robotcode analyze code tests/example.robot
66+
[W] KeywordNotFound: Some Undefined Keyword
67+
at tests/example.robot:5:5
68+
[E] VariableNotFound: Variable '${missing}' not found
69+
at tests/example.robot:6:11
70+
```
71+
72+
73+
## Scope of a Modifier
74+
75+
The effect of a modifier depends on its position in the file.
76+
77+
### At the End of a Line
78+
79+
A modifier placed at the end of a line affects **only that line**.
80+
81+
```robot
82+
*** Keywords ***
83+
Keyword Name
84+
Log ${arg1} # robotcode: ignore[variable-not-found]
85+
```
86+
87+
Here, the `variable-not-found` error is ignored only for this `Log` call.
88+
89+
### At the Beginning of a Line (Column 0)
90+
91+
A modifier placed at the very beginning of a line applies **from that line to the end of the file**, unless it is overridden or reset by another modifier.
92+
93+
```robot
94+
# robotcode: ignore[keyword-not-found]
95+
*** Test Cases ***
96+
Example Test
97+
Log Hello
98+
Some Undefined Keyword
99+
```
100+
101+
From the position of this modifier to the end of the file, all `keyword-not-found` errors are ignored.
102+
103+
### Inside a Block (Indented)
104+
105+
A modifier that is indented and therefore lies inside a block (for example a Test Case, Keyword, IF, FOR) only applies to the **current block**.
106+
107+
```robot
108+
*** Keywords ***
109+
Example Keyword
110+
# robotcode: warn[variable-not-found]
111+
Log ${arg1}
112+
Another Keyword
113+
```
114+
115+
Within the `Example Keyword` block, `variable-not-found` errors are treated as warnings.
116+
117+
118+
## Typical Use Cases
119+
120+
### Ignore a Single Diagnostic on One Line
121+
122+
```robot
123+
*** Keywords ***
124+
Show Debug Value
125+
Log ${possibly_undefined} # robotcode: ignore[variable-not-found]
126+
```
127+
128+
Useful when you deliberately work with optional or dynamic variables.
129+
130+
### Treat a Rule Globally as "Hint"
131+
132+
```robot
133+
# robotcode: hint[MultipleKeywords]
134+
*** Test Cases ***
135+
My Test
136+
Some Keyword
137+
Another Keyword
138+
```
139+
140+
The `MultipleKeywords` diagnostic is treated as a hint from this point onward instead of a warning or error.
141+
142+
### Warning Instead of Error for a Specific Rule
143+
144+
```robot
145+
# robotcode: warn[variable-not-found]
146+
*** Test Cases ***
147+
Experimental Test
148+
Log ${undefined_variable}
149+
```
150+
151+
`variable-not-found` stays visible but does not block you as an error.
152+
153+
### Combine Multiple Actions in One Comment
154+
155+
```robot
156+
# robotcode: warn[keyword-not-found] ignore[variable-not-found]
157+
*** Test Cases ***
158+
Mixed Strictness
159+
Some Undefined Keyword
160+
Log ${maybe_missing}
161+
```
162+
163+
Here, `keyword-not-found` is downgraded to a warning while `variable-not-found` is ignored for the same lines; the actions are applied left to right.
164+
165+
### Enforce Strict Checking for a Single Rule
166+
167+
```robot
168+
# robotcode: error[keyword-not-found]
169+
*** Test Cases ***
170+
Critical Test
171+
Some Undefined Keyword
172+
```
173+
174+
`keyword-not-found` is treated as an error in this area, even if it is globally configured as a warning or hint.
175+
176+
### Fine-Grained Control with `reset`
177+
178+
```robot
179+
# robotcode: error[variable-not-found]
180+
*** Test Cases ***
181+
Example Test
182+
Log ${undefined_variable}
183+
184+
# robotcode: reset[variable-not-found]
185+
Another Test
186+
Log ${undefined_variable}
187+
```
188+
189+
- Until the `reset` modifier, `variable-not-found` is treated as an error.
190+
- After `reset[variable-not-found]` the global default severity for this rule is used again.
191+
192+
### Ignore All Diagnostics
193+
194+
```robot
195+
# robotcode: ignore
196+
*** Test Cases ***
197+
Example Test
198+
Log ${undefined_variable}
199+
Some Undefined Keyword
200+
```
201+
202+
From this point on, all diagnostics are ignored.
203+
204+
### Reset All Diagnostics
205+
206+
```robot
207+
# robotcode: ignore
208+
*** Test Cases ***
209+
Example Test
210+
Log ${undefined_variable}
211+
212+
# robotcode: reset
213+
Another Test
214+
Some Undefined Keyword
215+
```
216+
217+
- Until the `reset` modifier, all diagnostics are ignored.
218+
- After `reset`, all messages are reported again with their default severity.
219+
220+
221+
## Best Practices
222+
223+
- **Keep modifiers local:** Prefer modifiers that are limited to a single line or block instead of globally disabling diagnostics for large parts of a file.
224+
- **Document commonly used diagnostic codes:** If you use modifiers frequently in a project, document the most important codes (for example `variable-not-found`, `keyword-not-found`, `MultipleKeywords`) for your team.
225+
- **Use `reset` consistently:** Especially when using `ignore` or `error` at the top of a file, make sure there is a clear `reset` later so that the effect does not unintentionally extend when code is moved or added.
226+
- **Consider code review:** Because modifiers change the analysis results, they should be part of code review and consciously approved.
227+
228+
229+
### Configuration via `robot.toml`
230+
231+
Global diagnostic modifiers are usually configured in the
232+
`[tool.robotcode-analyze.modifiers]` section of a TOML configuration file,
233+
typically the workspace-level `robot.toml` or the local `.robot.toml` file (see
234+
[config.md](config.md) for details).
235+
236+
```toml
237+
[tool.robotcode-analyze.modifiers]
238+
# Completely ignore very noisy diagnostics
239+
ignore = ["MultipleKeywords"]
240+
241+
# Downgrade selected rules to warnings
242+
warning = ["variable-not-found"]
243+
244+
# Upgrade important rules to errors
245+
error = ["keyword-not-found"]
246+
247+
# Optional: treat all remaining diagnostics as hints
248+
hint = ["*"]
249+
```
250+
251+
- `ignore`, `error`, `warning`, `information`, `hint` are lists of diagnostic
252+
codes that are merged into the global modifier configuration.
253+
- If you want to **add** to existing lists without replacing them (for example when an extension provides defaults), use the matching `extend-*` keys, e.g. `extend-warning = ["variable-not-found"]`. See [config.md](config.md) for the full set.
254+
- You can use `"*"` as a wildcard to match all remaining diagnostics if needed.
255+
256+
RobotCode tools such as the analyzer, runner and CLI commands read these values
257+
from the configured TOML files and pass them as defaults into the diagnostics
258+
modifier engine. Inline `# robotcode:` modifiers in `.robot` files are then
259+
applied on top and always win for the affected line or block.
260+
261+
### Overriding via editor / language server settings
262+
263+
In addition to TOML configuration, the language server can also receive
264+
equivalent diagnostic modifier settings from the editor (for example VS Code
265+
`settings.json`). These modifier lists are combined with the values from
266+
`[tool.robotcode-analyze.modifiers]` and provide a convenient way to override
267+
or tweak project defaults per workspace or per developer.
268+
269+
In VS Code the corresponding settings live under the
270+
`robotcode.analysis.diagnosticModifiers.*` keys, for example:
271+
272+
```jsonc
273+
{
274+
"robotcode.analysis.diagnosticModifiers.ignore": [
275+
"MultipleKeywords"
276+
],
277+
"robotcode.analysis.diagnosticModifiers.warning": [
278+
"variable-not-found"
279+
],
280+
"robotcode.analysis.diagnosticModifiers.error": [
281+
"keyword-not-found"
282+
]
283+
}
284+
```
285+
286+
Typical scenarios are:
287+
288+
- keep the canonical, shared configuration in `robot.toml`, and
289+
- use editor settings only to temporarily relax or tighten certain rules
290+
(for example on a CI agent or for a specific developer machine).

‎docs/03_reference/index.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,11 @@
11
# Reference
22

3-
This reference provides a comprehensive resource for effectively using and configuring the `robotcode` tool in Robot Framework projects. It covers two main areas:
3+
This reference provides a comprehensive resource for effectively using and configuring the `robotcode` tool in Robot Framework projects. It covers the following areas:
44

55
- [**Command Line Interface (CLI)**](cli.md): Detailed guidance on using the `robotcode` CLI to manage tasks such as test execution, code analysis, debugging, and configuration management directly from the command line. Each CLI command is explained with descriptions, options, and examples to illustrate different use cases—from running tests in continuous integration (CI) environments to debugging specific test cases in development.
66

77
- [**`robot.toml` Configuration File**](config.md): The `robot.toml` file serves as a centralized configuration for managing settings in Robot Framework projects in a structured, maintainable way. This section provides a complete guide to the available settings in `robot.toml`, including instructions on creating profiles for different environments, extending or inheriting settings, and managing variables, libraries, and dependencies across testing scenarios. With `robot.toml`, teams can efficiently handle project configurations, reduce redundancy, and simplify the setup of complex test environments.
88

9+
- [**Diagnostic Modifiers**](diagnostics-modifiers.md): Explains how to control static analysis diagnostics (errors, warnings, hints) using inline `# robotcode:` comments and configuration in `robot.toml`. It covers the available modifier actions, their scope within Robot Framework files, and how global and inline settings interact across CLI, language server, and editor integrations.
10+
911
Together, these sections provide the knowledge needed to fully customize `robotcode` for a flexible and efficient testing workflow.

0 commit comments

Comments
 (0)