Code reference resolution docs for comment_references

See: #857

lib/src/rules/comment_references.dart

@@ -33,6 +33,16 @@ On the other hand, assuming `outOfScopeId` is out of scope:
 void f(int outOfScopeId) { ... }
 ```
 
+Note that the square bracket comment format is designed to allow 
+comments to refer to declarations using a fairly natural format 
+but does not allow *arbitrary expressions*.  In particular, code 
+references within square brackets can consist of either
+
+- a single identifier where the identifier is any identifier in scope for the comment (see the spec for what is in scope in doc comments),
+- two identifiers separated by a period where the first identifier is the name of a class that is in scope and the second is the name of a member declared in the class,
+- a single identifier followed by a pair of parentheses where the identifier is the name of a class that is in scope (used to refer to the unnamed constructor for the class), or
+- two identifiers separated by a period and followed by a pair of parentheses where the first identifier is the name of a class that is in scope and the second is the name of a named constructor (not strictly necessary, but allowed for consistency).
+
 ''';
 
 class CommentReferences extends LintRule {