DAS plugins: Update various docs

Work towards #61876

* Make a few notes about support beginning with Dart 3.10.
* Make a few notes indicating that plugins can only analyze Dart
  sources.
* Use the handy `> [!NOTE]` and `> [!WARNING]` syntax.
* Add a note about how plugins are resolved, and the dependency on
  analysis_server_plugin ^0.3.0.

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

Author: srawlins

pkg/analysis_server_plugin/README.md

@@ -1,6 +1,7 @@
 # analysis\_server\_plugin package
 
-This package offers support for writing Dart analysis server plugins.
+This package offers support for writing Dart analysis server plugins, for Dart
+3.10 (Flutter 3.38) and later.
 
 Analysis server plugins empower developers to contribute their own Dart static
 analysis in IDEs and at the command line via `dart analyze` and `flutter

pkg/analysis_server_plugin/doc/using_plugins.md

@@ -9,6 +9,8 @@ root of the package or workspace source tree. Analyzer plugins cannot be
 enabled, disabled, or otherwise specified or configured in a nested analysis
 options file
 
+Analyzer plugins are supported starting in Dart 3.10 (Flutter 3.38).
+
 Analyzer plugins are specified in the top-level `plugins` section:
 
 ```yaml
@@ -18,18 +20,18 @@ plugins:
 
 [workspace]: https://dart.dev/tools/pub/workspaces
 
-Note: This is similar to how analyzer plugins are enabled in the [legacy][]
-analyzer plugin system. However, in the legacy system, this `plugins` section
-is listed under the top-level `analyzer` section. In the new analyzer plugin
-system, `plugins` is a top-level section.
+> [!NOTE]
+> This is similar to how analyzer plugins are enabled in the [legacy][] analyzer
+plugin system. However, in the legacy system, this `plugins` section is listed
+under the top-level `analyzer` section. In the new analyzer plugin system,
+`plugins` is a top-level section.
 
 Individual plugins are listed similar to how dependencies are listed in a
 `pubspec.yaml` file; they are listed as a key-value pair, with the package name
 as the key. The value can either be
 
 * a package version constraint, in which case the package is downloaded from
   https://pub.dev,
-* a git dependency,
 * an absolute path.
 
 For example, while developing a plugin locally, it can be enabled as:
@@ -40,11 +42,21 @@ plugins:
     path: /path/to/my_plugin
 ```
 
-Note: after any change is made to the `plugins` section of an
-`analysis_options.yaml` file, the Dart Analysis Server must be restarted to see
-the effects.
+When the analysis server sees that a set of plugins is enabled, it creates a
+synthetic package which depends on each plugin package, which is loaded into a
+separate isolate of the analysis server process. It uses [`dart pub upgrade`][]
+to resolve a compatible set of versions of the plugin packages and their
+dependencies. Note that Dart 3.10 (Flutter 3.38) sets its own constraint on the
+`analysis_server_plugin` package, `^0.3.0`. This may change with each release
+of Dart and Flutter.
+
+> [!NOTE]
+> After any change is made to the `plugins` section of an
+> `analysis_options.yaml` file, the Dart Analysis Server must be restarted to
+> see the effects.
 
 [legacy]: https://github.com/dart-lang/sdk/blob/main/pkg/analyzer_plugin/doc/tutorial/tutorial.md
+[`dart pub upgrade`]: https://dart.dev/tools/pub/cmd/pub-upgrade
 
 ## Enabling a lint rule
 

pkg/analysis_server_plugin/doc/writing_rules.md

@@ -1,8 +1,8 @@
 # Writing rules
 
 This package gives analyzer plugin authors the ability to write static rules
-for source code. This document describes briefly how to write such a rule, and
-how to register it in an analyzer plugin.
+for Dart source code. This document describes briefly how to write such a rule,
+and how to register it in an analyzer plugin.
 
 ## Declaring an analysis rule
 
@@ -13,8 +13,8 @@ Every analysis rule is declared in two parts: a rule class that extends
 
 The rule class contains some general information about the rule, like its name
 and the diagnostic or diagnostics that the rule reports. It also registers the
-various syntax tree nodes that the visitor class needs to visit. Let's see an
-example:
+various Dart syntax tree nodes that the visitor class needs to visit. Let's see
+an example:
 
 ```dart
 import 'package:analyzer/analysis_rule/analysis_rule.dart';
@@ -174,7 +174,8 @@ See [writing a plugin][] for information about the `Plugin` class.
 
 ## Testing an analysis rule
 
-Writing tests for an analysis rule is very easy, and is documented at [testing rules][].
+Writing tests for an analysis rule is very easy, and is documented at [testing
+rules][].
 
 [writing a plugin]: https://github.com/dart-lang/sdk/blob/main/pkg/analysis_server_plugin/doc/writing_a_plugin.md
 [testing rules]: https://github.com/dart-lang/sdk/blob/main/pkg/analysis_server_plugin/doc/testing_rules.md

pkg/analyzer_plugin/README.md

@@ -3,11 +3,14 @@
 
 A framework for building plugins for the analysis server.
 
-> **WARNING!**  
-> This package is for **legacy support** and is **not recommended** for new plugin development.  
->  
-> For modern plugin implementations, use the [`analysis_server_plugin`](https://pub.dev/packages/analysis_server_plugin) package instead.  
->  
+> [!WARNING]
+> This package is for **legacy support** and is **not recommended** for new
+> plugin development.
+>
+> For modern plugin implementations, use the
+> [`analysis_server_plugin`](https://pub.dev/packages/analysis_server_plugin)
+> package instead.
+>
 > See its documentation for the latest architecture and examples.
 
 ## Usage