Add documentation for the deprecated_factory_method warning

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

Author: bwilkerson

pkg/analyzer/messages.yaml

@@ -25335,6 +25335,49 @@ WarningCode:
     problemMessage: Methods named 'factory' will become constructors when the primary_constructors feature is enabled.
     correctionMessage: Try adding a return type or modifier before the method's name, or change the name of the method.
     hasPublishedDocs: false
+    documentation: |-
+      #### Description
+
+      The analyzer produces this diagnostic when the declaration of an instance
+      method named `factory` is interpreted as a constructor declaration after
+      the `primary_constructors` feature is enabled.
+
+      This issue only affects declarations that lack a return type and where the
+      method name is the first token or is preceded only by `external`,
+      `augment`, or `augment external`. The `augment` and `augment external`
+      keywords are valid only after the augmentations feature is enabled.
+
+      #### Example
+
+      The following code produces this diagnostic because the instance method
+      named `factory` has no return type or modifiers:
+
+      ```dart
+      // @dart=3.10
+      class C {
+        [!factory!]() => C();
+      }
+      ```
+
+      #### Common fixes
+
+      If the name can be changed, then rename the method:
+
+      ```dart
+      // @dart=3.10
+      class C {
+        make() => C();
+      }
+      ```
+
+      If the name must remain `factory`, then add a return type:
+
+      ```dart
+      // @dart=3.10
+      class C {
+        C factory() => C();
+      }
+      ```
   deprecatedImplement:
     type: staticWarning
     parameters: