[analyzer] Document that clients shouldn't create classes based on SyntacticEntity.

We never intended for clients to be able to create their own classes
that implement `SyntacticEntity`. Explicitly documenting that they
shouldn't do so makes it safer to add members to the class in the
future.

Change-Id: I6a6a696465b98a1f3363222e9e61889514110ba9
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/467644
Commit-Queue: Paul Berry <paulberry@google.com>
Reviewed-by: Brian Wilkerson <brianwilkerson@google.com>
Reviewed-by: Konstantin Shcheglov <scheglov@google.com>

Author: stereotype441

pkg/_fe_analyzer_shared/lib/src/base/syntactic_entity.dart

@@ -6,6 +6,8 @@ import 'package:_fe_analyzer_shared/src/base/analyzer_public_api.dart';
 
 /// Interface representing a syntactic entity (either a token or an AST node)
 /// which has a location and extent in the source file.
+///
+/// Clients may not extend, implement or mix-in this class.
 @AnalyzerPublicApi(
   message: 'exported by package:analyzer/dart/ast/syntactic_entity.dart',
 )

pkg/analyzer/CHANGELOG.md

@@ -31,6 +31,8 @@
   Use `isOriginDeclaration`, `isOriginInterface`, `isOriginVariable` instead.
 * Deprecate `Element.isSynthetic`, use `isOriginXyz` properties instead.
 * Deprecate `LibraryElement.isSynthetic`, use `isOriginNotExistingFile` instead.
+* Document that the class `SyntacticEntity` is not intended to be subclassed by
+  clients.
 
 ## 9.0.0
 * Remove deprecated field `Diagnostic.data`.