docs: fix inline examples, deprecation descriptions, type category

Replicates graphql/graphql-js@3b30a64

Author: Cito

src/graphql/error/graphql_error.py

@@ -254,6 +254,8 @@ def print_error(error: GraphQLError) -> str:
     """Print a GraphQLError to a string.
 
     Represents useful location information about the error's position in the source.
+    This deprecated helper is retained for backwards compatibility; call ``str(error)``
+    instead because ``print_error`` will be removed in v3.3.
 
     .. deprecated:: 3.2
        Please use ``str(error)`` instead. Will be removed in v3.3.
@@ -267,7 +269,9 @@ def format_error(error: GraphQLError) -> GraphQLFormattedError:
     """Format a GraphQL error.
 
     Given a GraphQLError, format it according to the rules described by the "Response
-    Format, Errors" section of the GraphQL Specification.
+    Format, Errors" section of the GraphQL Specification. This deprecated helper is
+    retained for backwards compatibility; use ``error.formatted`` instead because
+    ``format_error`` will be removed in v3.3.
 
     .. deprecated:: 3.2
        Please use ``error.formatted`` instead. Will be removed in v3.3.

src/graphql/language/parser.py

@@ -113,6 +113,11 @@ def parse(
     :attr:`~graphql.language.FragmentDefinitionNode.variable_definitions` field
     of the :class:`~graphql.language.FragmentDefinitionNode`.
 
+    This legacy fragment variable syntax is deprecated. Move variable definitions to
+    operations for spec-compliant documents; if you need variables or arguments scoped
+    to fragments, the more complete experimental fragment-arguments feature in
+    graphql-core 3.3 should be used instead.
+
     The syntax is identical to normal, query-defined variables. For example::
 
         fragment A($var: Boolean = false) on T  {

src/graphql/language/visitor.py

@@ -149,6 +149,10 @@ def get_visit_fn(
     ) -> Optional[Callable[..., Optional[VisitorAction]]]:
         """Get the visit function for the given node kind and direction.
 
+        This deprecated compatibility helper delegates to
+        ``get_enter_leave_for_kind``; call ``get_enter_leave_for_kind`` directly
+        because ``get_visit_fn`` will be removed in v3.3.
+
         .. deprecated:: 3.2
            Please use ``get_enter_leave_for_kind`` instead. Will be removed in v3.3.
         """

src/graphql/utilities/assert_valid_name.py

@@ -9,6 +9,9 @@
 def assert_valid_name(name: str) -> str:
     """Uphold the spec rules about naming.
 
+    This deprecated helper is retained for backwards compatibility; call ``assert_name``
+    instead because ``assert_valid_name`` will be removed in v3.3.
+
     .. deprecated:: 3.2
        Please use ``assert_name`` instead. Will be removed in v3.3.
     """
@@ -21,6 +24,10 @@ def assert_valid_name(name: str) -> str:
 def is_valid_name_error(name: str) -> Optional[GraphQLError]:
     """Return an Error if a name is invalid.
 
+    This deprecated helper is retained for backwards compatibility; call ``assert_name``
+    and catch the raised GraphQLError instead because ``is_valid_name_error`` will be
+    removed in v3.3.
+
     .. deprecated:: 3.2
        Please use ``assert_name`` instead. Will be removed in v3.3.
     """

src/graphql/utilities/ast_from_value.py

@@ -38,9 +38,7 @@ def ast_from_value(value: Any, type_: GraphQLInputType) -> Optional[ValueNode]:
     """Produce a GraphQL Value AST given a Python object.
 
     This function will match Python/JSON values to GraphQL AST schema format by using
-    the suggested GraphQLInputType. For example::
-
-        ast_from_value('value', GraphQLString)
+    the suggested GraphQLInputType.
 
     A GraphQL type must be provided, which will be used to interpret different Python
     values.

src/graphql/utilities/get_operation_root_type.py

@@ -17,8 +17,12 @@ def get_operation_root_type(
 ) -> GraphQLObjectType:
     """Extract the root type of the operation from the schema.
 
+    This deprecated helper is retained for backwards compatibility; call
+    :meth:`GraphQLSchema.get_root_type <graphql.type.GraphQLSchema.get_root_type>`
+    instead because ``get_operation_root_type`` will be removed in v3.3.
+
     .. deprecated:: 3.2
-       Please use `GraphQLSchema.getRootType` instead. Will be removed in v3.3.
+       Please use ``GraphQLSchema.get_root_type`` instead. Will be removed in v3.3.
     """
     operation_type = operation.operation
     if operation_type == OperationType.QUERY:

src/graphql/utilities/type_info.py

@@ -74,7 +74,8 @@ def __init__(
         Initial type may be provided in rare cases to facilitate traversals beginning
         somewhere other than documents.
 
-        The optional last parameter is deprecated and will be removed in v3.3.
+        The optional ``get_field_def_fn`` parameter is deprecated; omit it so that
+        TypeInfo uses its built-in field definition lookup. It will be removed in v3.3.
         """
         self._schema = schema
         self._type_stack: List[Optional[GraphQLOutputType]] = []

src/graphql/validation/validate.py

@@ -48,7 +48,8 @@ def validate(
     Attackers can send pathologically invalid queries to induce a DoS attack,
     so by default ``max_errors`` set to 100 errors.
 
-    Providing a custom TypeInfo instance is deprecated and will be removed in v3.3.
+    Providing a custom TypeInfo instance is deprecated; omit the ``type_info``
+    argument so that validate creates the TypeInfo instance. It will be removed in v3.3.
     """
     if not document_ast or not isinstance(document_ast, DocumentNode):
         raise TypeError("Must provide document.")