Document the sample API doc analyzer (#14740)

dev/bots/analyze-sample-code.dart

@@ -2,6 +2,41 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
+// This script analyzes all the sample code in API docs in the Flutter source.
+//
+// It uses the following conventions:
+//
+// Code is denoted by markdown ```dart / ``` markers.
+//
+// Only code in "## Sample code" or "### Sample code" sections is examined.
+//
+// There are several kinds of sample code you can specify:
+//
+// * Constructor calls, typically showing what might exist in a build method.
+//   These start with "new" or "const", and will be inserted into an assignment
+//   expression assigning to a variable of type "dynamic" and followed by a
+//   semicolon, for the purposes of analysis.
+//
+// * Class definitions. These start with "class", and are analyzed verbatim.
+//
+// * Other code. It gets included verbatim, though any line that says "// ..."
+//   is considered to separate the block into multiple blocks to be processed
+//   individually.
+//
+// In addition, you can declare code that should be included in the analysis but
+// not shown in the API docs by adding a comment "// Examples can assume:" to
+// the file (usually at the top of the file, after the imports), following by
+// one or more commented-out lines of code. That code is included verbatim in
+// the analysis.
+//
+// All the sample code of every file is analyzed together. This means you can't
+// have two pieces of sample code that define the same example class.
+//
+// Also, the above means that it's tricky to include verbatim imperative code
+// (e.g. a call to a method), since it won't be valid to have such code at the
+// top level. Instead, wrap it in a function or even a whole class, or make it a
+// valid variable declaration.
+
 import 'dart:async';
 import 'dart:convert';
 import 'dart:io';