documentation / fix incorrect and outdated statements (#139)

- Analysis runs on open, save and tab switch, not only on save (#75).
- Header warnings are shown (except with a project file) and critical
  errors are always shown (#77, #33).
- A header's warnings stay while another open file includes it.
- Project-file suppressions only work with .cppcheck files.
- Cppcheck Premium works without extra setup (#114).
- Link both the open source and the Premium manual, with corrected
  page anchors.
- Fix typos.

Fixes #128

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Author: danmar

README.md

@@ -1,22 +1,22 @@
 # Cppcheck Official
 
 
-**Cppcheck Official** is a Visual Studio Code extension that runs [cppcheck](https://cppcheck.sourceforge.io/) against C/C++ files upon save and reports any warnings or errors in the Problems panel.
+**Cppcheck Official** is a Visual Studio Code extension that runs [cppcheck](https://cppcheck.sourceforge.io/) against C/C++ files when you open, save or switch to them, and reports any warnings or errors in the Problems panel.
 
 ![Image showing example of problem tab with warnings output from cppcheck](./images/check_result2.png)
 
 ## Features
-- **On-save linting**: When you save a c/cpp file, `cppcheck` is automatically run on that file.
-- **Per-file diagnostics**: Only diagnostics relevant to the saved file are displayed.
+- **Automatic analysis**: `cppcheck` runs automatically on a C/C++ file when you open it, save it or switch to its tab.
+- **Diagnostics for the analysed file and its headers**: Warnings for the analysed file are shown, together with warnings in the header files it includes (unless a project file is used, in which case only the analysed file's warnings are shown). Critical errors, such as `syntaxError`, are always shown.
 - **Configurable severity threshold**: Filter out messages below a chosen severity level (`info`, `warning`, or `error`).
-- **Diagnostic cleanup**: When you close a file, its diagnostics are automatically cleared.
+- **Diagnostic cleanup**: When you close a file, its diagnostics are automatically cleared. Warnings in a header file stay as long as another open file that includes it is still open.
 - **Project file support**: You can feed your project file to cppcheck through the `--project` flag in the `cppcheck-official.arguments` field in the extension settings. (See image below)
 
 ![Image showing where to set up project file](./images/project_file.png)
 - **Warning notes**: Display notes for warnings when those are available
 - **Dynamic config**: The extension supports running a script to generate arguments to pass to cppcheck. This can be done by including the command in the argument field wrapped with \@(), e.g. `--suppress=memleak:src/file1.cpp @(bash path/to/script.sh)`. The script is expected to output the argument(s) wrapped with \@(). If the script e.g. creates a project file it should print out as `@(--project=path/to/projectfile.json)`. This output will be spliced into the argument string as such: `--suppress=memleak:src/file1.cpp --project=path/to/projectfile.json`.
 
-- **Warning suppression**: Warnings of a specific type can be supressed with the --suppress flag in the argument field in the extension settings. The extension also supports inline suppression for specific lines of code, simply write `// cppcheck-suppress >warning id<` (see image below). Suppressions can also be added through code actions, either as automatically generated inline suppressions or, if you are using a project file, as universal suppressions specified in your project file.
+- **Warning suppression**: Warnings of a specific type can be suppressed with the `--suppress` flag in the argument field in the extension settings. The extension also supports inline suppression for specific lines of code, simply write `// cppcheck-suppress <warning id>` (see image below). Suppressions can also be added through code actions, either as automatically generated inline suppressions or, if you are using a `.cppcheck` project file, as universal suppressions specified in your project file. Adding suppressions to the project file is not supported for `compile_commands.json` or other project types.
 ![Image showing how to suppress warnings](./images/suppression.png)
 ## Requirements
 
@@ -37,8 +37,8 @@ This extension contributes the following settings under `cppcheck-official.*`:
 
 - **`cppcheck-official.enable`**: (boolean) Enable or disable the extension.  
 - **`cppcheck-official.minSeverity`**: (string) Minimum severity to report (`info`, `warning`, or `error`).  `info` shows style, performance, portability and information messages.
-- **`cppcheck-official.arguments`**: (string) Additional [command line arguments](https://cppcheck.sourceforge.io/manual.pdf?#page=5) to pass to `cppcheck`.  
-- **`cppcheck-official.path`**: (string) Path to the `cppcheck` executable (i.e. `/path/to/cppcheck.exe`). If left empty, `cppcheck` from the system PATH is used. Supports paths relative to workspace folder on the formats `./RELATIVE_PATH`, `../RELATIVE_PATH` or `${workspaceFolder}/RELATIVE_PATH`.
+- **`cppcheck-official.arguments`**: (string) Additional command line arguments to pass to `cppcheck`. See the Cppcheck manual ([open source](https://cppcheck.sourceforge.io/manual.pdf#page=4) / [Premium](https://files.cppchecksolutions.com/manual.pdf#page=4)).  
+- **`cppcheck-official.path`**: (string) Path to the `cppcheck` executable (e.g. `/path/to/cppcheck.exe`). If left empty, `cppcheck` from the system PATH is used. Supports paths relative to workspace folder on the formats `./RELATIVE_PATH`, `../RELATIVE_PATH` or `${workspaceFolder}/RELATIVE_PATH`.
 
 ## Shared Settings File
 

package.json

@@ -1,7 +1,7 @@
 {
   "name": "cppcheck-official",
   "displayName": "Cppcheck Official",
-  "description": "A Visual Studio Code extension that runs cppcheck on C/C++ files on save. Supported by the Cppcheck team.",
+  "description": "A Visual Studio Code extension that runs cppcheck on C/C++ files when they are opened, saved or switched to. Supported by the Cppcheck team.",
   "version": "1.0.16",
   "engines": {
     "vscode": "^1.96.0"
@@ -62,12 +62,12 @@
           "cppcheck-official.path": {
             "type": "string",
             "default": "",
-            "description": "Path to the cppcheck executable (i.e. `/path/to/cppcheck.exe`). If empty, uses 'cppcheck' from the system PATH."
+            "description": "Path to the cppcheck executable (e.g. `/path/to/cppcheck.exe`). If empty, uses 'cppcheck' from the system PATH."
           },
           "cppcheck-official.arguments": {
             "type": "string",
             "default": "",
-            "markdownDescription": "Additional command line arguments for cppcheck. Use spaces to separate multiple arguments. For documentation see: [Cppcheck documentation](https://files.cppchecksolutions.com/manual.pdf). Overridden by `arguments` in `cppcheck.json` in the workspace folder, if present.",
+            "markdownDescription": "Additional command line arguments for cppcheck. Use spaces to separate multiple arguments. For documentation see the Cppcheck manual ([open source](https://cppcheck.sourceforge.io/manual.pdf#page=4) / [Premium](https://files.cppchecksolutions.com/manual.pdf#page=4)). Overridden by `arguments` in `cppcheck.json` in the workspace folder, if present.",
             "description": "Additional command line arguments for cppcheck. Use spaces to separate multiple arguments."
           }
         }

walkthrough/arguments.md

@@ -1,12 +1,12 @@
 
 
-Cppcheck works best for you if you set it up according to your needs. You may e.g. want to disable certain kinds of warnings, and if you have cppcheck premium you will need to set this up for it to work in this extension. All of this is done through the extension property 'arguments', with the different flags or arguments available being detailed in the [official cppcheck documentation](https://files.cppchecksolutions.com/manual.pdf#page=13).
+Cppcheck works best for you if you set it up according to your needs. You may e.g. want to disable certain kinds of warnings. Cppcheck Premium works without extra setup, but Premium checks such as `--premium=misra-c-2023` have to be enabled. All of this is done through the extension property 'arguments', with the different flags or arguments available being detailed in the Cppcheck manual ([open source](https://cppcheck.sourceforge.io/manual.pdf#page=4) / [Premium](https://files.cppchecksolutions.com/manual.pdf#page=4)). The Premium checks are described in the [Premium manual](https://files.cppchecksolutions.com/manual.pdf#page=44).
 
-To make sure that you and your team work with the same set up, it is recommended to put the arguments in a `cppcheck.json` file in the root of your workspace and commit it to version control, e.g. `{ "arguments": "--project=build/compile_commands.json" }`. Arguments in this file take precedence over the arguments setting. Furthermore you are likely to want to have the same settings between VS Code and your CI workflows. This is most easily done through project files, which are referenced from the argument setting (see [documentation](https://files.cppchecksolutions.com/manual.pdf#page=4) for how to create a project file).
+To make sure that you and your team work with the same set up, it is recommended to put the arguments in a `cppcheck.json` file in the root of your workspace and commit it to version control, e.g. `{ "arguments": "--project=build/compile_commands.json" }`. Arguments in this file take precedence over the arguments setting. Furthermore you are likely to want to have the same settings between VS Code and your CI workflows. This is most easily done through project files, which are referenced from the argument setting (see the Cppcheck manual ([open source](https://cppcheck.sourceforge.io/manual.pdf#page=10) / [Premium](https://files.cppchecksolutions.com/manual.pdf#page=10)) for how to create a project file).
 
 ![image showing project file path being set in arguments property](../images/project_file.png)
 
-Another way of synching your set up between different environments is through using scripts. The argument property supports running scripts with the syntax `@(/path/to/script.sh)`. The extension expects this script to output what to use for arguments wrapped with `@()`, so e.g. `echo "@(--report-progress --enable=style --inconclusive --suppress=syntaxError)"`.
+Another way of syncing your set up between different environments is through using scripts. The argument property supports running scripts with the syntax `@(/path/to/script.sh)`. The extension expects this script to output what to use for arguments wrapped with `@()`, so e.g. `echo "@(--report-progress --enable=style --inconclusive --suppress=syntaxError)"`.
 
 
 [Set up arguments](command:cppcheck-official.configureArguments)

walkthrough/test.md

@@ -1,5 +1,5 @@
 ![Image showing cppcheck warnings in the problems tab.](../images/check_result2.png)
 
-Open a .c or .cpp file and save it. If cppcheck detects any issues these will show up in the problems tab in the bottom of your VS Code window.
+Open a .c or .cpp file. Cppcheck analyses it when it is opened and again every time you save it. If cppcheck detects any issues these will show up in the problems tab in the bottom of your VS Code window.
 
-The extension is in continuous development, so if you find issues, have feature requests or some other kind of feedback we are happy to recieve it at the [Cppcheck Official github page](https://github.com/cppchecksolutions/vscode-cppcheck-official/issues).
+The extension is in continuous development, so if you find issues, have feature requests or some other kind of feedback we are happy to receive it at the [Cppcheck Official github page](https://github.com/cppchecksolutions/vscode-cppcheck-official/issues).