DAS: document enabling lint rule and suppressing

Change-Id: I26504b84c3a899c4f9f80d8a35f6c2c622c5613c
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/416181
Reviewed-by: Johnni Winther <[email protected]>
Commit-Queue: Samuel Rawlins <[email protected]>
Reviewed-by: Brian Wilkerson <[email protected]>

Author: srawlins

pkg/analysis_server_plugin/doc/using_plugins.md

@@ -5,7 +5,7 @@ can be enabled for a given package, so that the plugin can report diagnostics
 (lints and warnings) and offer quick fixes. Plugins are enabled via the
 `analysis_options.yaml` file under the top-level `plugins` section:
 
-```
+```yaml
 plugins:
   my_plugin: ^1.0.0
 ```
@@ -26,7 +26,7 @@ as the key. The value can either be
 
 For example, while developing a plugin locally, it can be enabled as:
 
-```
+```yaml
 plugins:
   my_plugin:
     path: /path/to/my_plugin
@@ -37,3 +37,39 @@ Note: after any change is made to the `plugins` section of an
 the effects.
 
 [legacy]: https://github.com/dart-lang/sdk/blob/main/pkg/analyzer_plugin/doc/tutorial/tutorial.md
+
+## Enabling a lint rule
+
+A plugin can report two kinds of diagnostics: warnings and lints. Any warnings
+that a plugin defines are enabled by default (like analyzer warnings). Any lint
+rules that a plugin defines are disabled by default (like analyzer lint rules),
+and must be explicitly enabled in analysis options. Lint rules are enabled
+under the `diagnostics` section for a plugin:
+
+```yaml
+plugins:
+  my_plugin:
+    path: /path/to/my_plugin
+    diagnostics:
+      rule_1: true
+      rule_2: true
+      rule_3: false
+```
+
+In the configuration above, `rule_1` and `rule_2` are enabled. Additionally,
+`rule_3` is disabled, which can be useful if an included analysis options file
+explicitly enables the rule.
+
+## Suppressing diagnostics
+
+A diagnostic which is reported by a plugin can be suppressed with a comment. The
+syntax is similar to suppressing an out-of-the-box warning or lint diagnostic
+(see [the docs](https://dart.dev/tools/analysis#suppressing-diagnostics-for-a-file)).
+To suppress a warning or lint named "some_code" in a plugin named "some_plugin,"
+use a comment like the following:
+
+```dart
+// ignore: some_plugin/some_code
+
+// ignore_for_file: some_plugin/some_code
+```