Revise docstring and documentation for consistency.

python · jeremyhylton · May 22, 2024 · Mar 28, 2020 · Mar 31, 2020 · May 11, 2024
commit c0bb0e91efd624cd69284ee2f6fe4231ff5009c9
diff --git a/Doc/library/ast.rst b/Doc/library/ast.rst
@@ -2472,15 +2472,23 @@ effects on the compilation of a program:
    .. versionadded:: 3.8
 
 
-.. function:: compare(a, b, /, *, compare_types=True, compare_fields=True, compare_attributes=False)
+.. function:: compare(a, b, /, *, compare_types=True, compare_attributes=False)
 
-    Recursively compare given 2 AST nodes. If *compare_types* is ``False``, the
-    field values won't be checked whether they belong to same type or not. If
-    *compare_fields* is ``True``, members of ``_fields`` attribute on both node's
-    type will be checked. If *compare_attributes* is ``True``, members of
-    ``_attributes`` attribute on both node's will be compared.
+   Recursively compares two ast nodes.
 
-   .. versionadded:: 3.9
+   There are two options that control how the comparison is done. If
+   *compare_types* is ``True`` (default), then Constant objects must
+   have the same type and value to be equal. If *compare_types* is
+   ``False``, then Constant objects must only have the same values,
+   e.g. Constant(1.0) equals Constant(1).
+
+
+   *compare_attributes* affects whether AST attributes are considered
+   in the comparison. If compare_attributes is ``False`` (default), then
+   attributes are ignored. Otherwise they must all be equal. This
+   option is useful to look for asts that are structurally equal but
+   might differ in whitespace or similar details.
+   .. versionadded:: 3.14
 
 
 .. _ast-cli:

@@ -409,15 +409,15 @@ def compare(
     compare_types=True,
     compare_attributes=False,
 ):
-    """Compares recursively given two ast nodes.
+    """Recursively compares two ast nodes.
 
     There are two options that control how the comparison is done.
 
-    compare_types affects how Constant values are compared. If
-    compare_types is True (default), then Constant values must have
+    compare_types affects how Constant objects are compared. If
+    compare_types is True (default), then Constant objects must have
     the same type and value to be equal. If compare_type is False,
-    then Constant values will compare equal if the type Python objects
-    are equal regardless of type, e.g. 1.0 == 1.
+    then Constant objects must only have the same value,
+    e.g. Constant(1.0) equals Constant(1).
 
     compare_attributes affects whether AST attributes are considered
     in the comparison. If compare_attributes is False (default), then