update documentation about hints / diagnostic tags

docs/benefits-over-pyright/language-server-improvements.md

@@ -12,7 +12,7 @@ autocomplete suggestions for method overrides will automatically add the `@overr
 
 in pyright, certain diagnostics such as unreachable and unused code are always reported as a hint and cannot be disabled even when the associated diagnostic rule is disabled (and in the case of unreachable code, [there is no diagnostic rule at all](./new-diagnostic-rules.md#reportunreachable)).
 
-basedpyright introduces a new [`"hint"`](../configuration/config-files.md#diagnostic-categories) diagnostic category which can be applied to any diagnostic rule, and can be disabled just like all other diagnostic rules. diagnostics that are reported as a `"hint"` can have diagnostic tags (unused or deprecated) that change how they're displayed if supported by your IDE, if such a tag is relevant for that rule:
+basedpyright introduces a new [`"hint"`](../configuration/config-files.md#diagnostic-categories) diagnostic category which can be applied to any diagnostic rule, and can be disabled just like all other diagnostic rules. some diagnostics use a diagnostic tag (unused or deprecated) if your IDE supports them:
 
 ```toml title="pyproject.toml"
 [tool.basedpyright]
@@ -26,6 +26,8 @@ here's how they look in vscode:
 
 ![](diagnostic-tags.png)
 
+these diagnostic tags will still be present if the rule's diagnostic category is set to `"warning"`, `"error"` or `"information"`, but unlike pyright, they are disabled entirely if the rule's diagnostic category is set to `"none"`.
+
 ## deprecated completions
 
 pyright/pylance supports strikethrough diagnostic tags on usages of deprecated symbols:

docs/configuration.md

@@ -87,12 +87,13 @@ diagnostics can be configured to be reported as any of the following categories:
 - `"warning"` - only causes the CLI to fail if [`failOnWarnings`](#failOnWarnings) is enabled or the [`--warnings`](./command-line.md#command-line) argument is used
 - `"information"` - never causes the CLI to fail
 - `"hint"` - only appears as a hint in the language server, not reported in the CLI at all. [baselined diagnostics](../benefits-over-pyright/baseline.md) are reported as hints
+- `"none"` - disables the diagnostic entirely
 
-!!! note
-    the `"unreachable"`, `"unused"` and `"deprecated"` diagnostic categories are deprecated in favor of `"hint"`. rules where it makes sense
+!!! info "deprecated diagnostic categories"
+    as of basedpyright 1.21.0, the `"unreachable"`, `"unused"` and `"deprecated"` diagnostic categories are deprecated in favor of `"hint"`. rules where it makes sense
     to report them as "unnecessary" or "deprecated" [as mentioned in the LSP spec](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#diagnosticSeverity) are still reported as such, the configuration to do so has just been simplified.
 
-    the `"hint"` diagnostic category is more flexible as it can be used on rules that don't refer to something that's unused, unreachable or deprecated. [baselined diagnostics](../benefits-over-pyright/baseline.md) are now all reported as a hint, instead of just the ones that supported one of the specific diagnostic tag categories.
+    the `"hint"` diagnostic category is more flexible as it can be used on rules that don't refer to something that's unused, unreachable or deprecated. [baselined diagnostics](../benefits-over-pyright/baseline.md) are now all reported as hints, even ones that don't support diagnostic tags.
 
     for backwards compatibility, setting a diagnostic rule to any of these three deprecated categories will act as an alias for the `"hint"` category, however they may be removed entirely in a future release.