Improve documentation of validation rules

Add links to the specification for GraphQL

Replicates graphql/graphql-js@0c7165a

Author: Cito

src/graphql/validation/rules/executable_definitions.py

@@ -21,6 +21,8 @@ class ExecutableDefinitionsRule(ASTValidationRule):
 
     A GraphQL document is only valid for execution if all definitions are either
     operation or fragment definitions.
+
+    See https://spec.graphql.org/draft/#sec-Executable-Definitions
     """
 
     def enter_document(self, node: DocumentNode, *_args: Any) -> VisitorAction:

src/graphql/validation/rules/fields_on_correct_type.py

@@ -25,6 +25,8 @@ class FieldsOnCorrectTypeRule(ValidationRule):
 
     A GraphQL document is only valid if all fields selected are defined by the parent
     type, or are an allowed meta field such as ``__typename``.
+
+    See https://spec.graphql.org/draft/#sec-Field-Selections
     """
 
     def enter_field(self, node: FieldNode, *_args: Any) -> None:

src/graphql/validation/rules/fragments_on_composite_types.py

@@ -19,6 +19,8 @@ class FragmentsOnCompositeTypesRule(ValidationRule):
     Fragments use a type condition to determine if they apply, since fragments can only
     be spread into a composite type (object, interface, or union), the type condition
     must also be a composite type.
+
+    See https://spec.graphql.org/draft/#sec-Fragments-On-Composite-Types
     """
 
     def enter_inline_fragment(self, node: InlineFragmentNode, *_args: Any) -> None:

src/graphql/validation/rules/known_argument_names.py

@@ -68,6 +68,9 @@ class KnownArgumentNamesRule(KnownArgumentNamesOnDirectivesRule):
     """Known argument names
 
     A GraphQL field is only valid if all supplied arguments are defined by that field.
+
+    See https://spec.graphql.org/draft/#sec-Argument-Names
+    See https://spec.graphql.org/draft/#sec-Directives-Are-In-Valid-Locations
     """
 
     context: ValidationContext

src/graphql/validation/rules/known_directives.py

@@ -19,6 +19,8 @@ class KnownDirectivesRule(ASTValidationRule):
 
     A GraphQL document is only valid if all ``@directives`` are known by the schema and
     legally positioned.
+
+    See https://spec.graphql.org/draft/#sec-Directives-Are-Defined
     """
 
     context: Union[ValidationContext, SDLValidationContext]

src/graphql/validation/rules/known_fragment_names.py

@@ -12,6 +12,8 @@ class KnownFragmentNamesRule(ValidationRule):
 
     A GraphQL document is only valid if all ``...Fragment`` fragment spreads refer to
     fragments defined in the same document.
+
+    See https://spec.graphql.org/draft/#sec-Fragment-spread-target-defined
     """
 
     def enter_fragment_spread(self, node: FragmentSpreadNode, *_args: Any) -> None:

src/graphql/validation/rules/known_type_names.py

@@ -21,6 +21,8 @@ class KnownTypeNamesRule(ASTValidationRule):
 
     A GraphQL document is only valid if referenced types (specifically variable
     definitions and fragment conditions) are defined by the type schema.
+
+    See https://spec.graphql.org/draft/#sec-Fragment-Spread-Type-Existence
     """
 
     def __init__(self, context: Union[ValidationContext, SDLValidationContext]):

src/graphql/validation/rules/lone_anonymous_operation.py

@@ -12,6 +12,8 @@ class LoneAnonymousOperationRule(ASTValidationRule):
 
     A GraphQL document is only valid if when it contains an anonymous operation
     (the query short-hand) that it contains only that one operation definition.
+
+    See https://spec.graphql.org/draft/#sec-Lone-Anonymous-Operation
     """
 
     def __init__(self, context: ASTValidationContext):

src/graphql/validation/rules/no_fragment_cycles.py

@@ -8,7 +8,14 @@
 
 
 class NoFragmentCyclesRule(ASTValidationRule):
-    """No fragment cycles"""
+    """No fragment cycles
+
+    The graph of fragment spreads must not form any cycles including spreading itself.
+    Otherwise an operation could infinitely spread or infinitely execute on cycles in
+    the underlying data.
+
+    See https://spec.graphql.org/draft/#sec-Fragment-spreads-must-not-form-cycles
+    """
 
     def __init__(self, context: ASTValidationContext):
         super().__init__(context)

src/graphql/validation/rules/no_undefined_variables.py

@@ -12,6 +12,8 @@ class NoUndefinedVariablesRule(ValidationRule):
 
     A GraphQL operation is only valid if all variables encountered, both directly and
     via fragment spreads, are defined by that operation.
+
+    See https://spec.graphql.org/draft/#sec-All-Variable-Uses-Defined
     """
 
     def __init__(self, context: ValidationContext):

src/graphql/validation/rules/no_unused_fragments.py

@@ -17,6 +17,8 @@ class NoUnusedFragmentsRule(ASTValidationRule):
 
     A GraphQL document is only valid if all fragment definitions are spread within
     operations, or spread within other fragments spread within operations.
+
+    See https://spec.graphql.org/draft/#sec-Fragments-Must-Be-Used
     """
 
     def __init__(self, context: ASTValidationContext):

src/graphql/validation/rules/no_unused_variables.py

@@ -12,6 +12,8 @@ class NoUnusedVariablesRule(ValidationRule):
 
     A GraphQL operation is only valid if all variables defined by an operation are used,
     either directly or within a spread fragment.
+
+    See https://spec.graphql.org/draft/#sec-All-Variables-Used
     """
 
     def __init__(self, context: ValidationContext):

src/graphql/validation/rules/overlapping_fields_can_be_merged.py

@@ -49,6 +49,8 @@ class OverlappingFieldsCanBeMergedRule(ValidationRule):
 
     A selection set is only valid if all fields (including spreading any fragments)
     either correspond to distinct response names or can be merged without ambiguity.
+
+    See https://spec.graphql.org/draft/#sec-Field-Selection-Mergin
     """
 
     def __init__(self, context: ValidationContext):

src/graphql/validation/rules/single_field_subscriptions.py

@@ -18,6 +18,8 @@ class SingleFieldSubscriptionsRule(ValidationRule):
 
     A GraphQL subscription is valid only if it contains a single root field and
     that root field is not an introspection field.
+
+    See https://spec.graphql.org/draft/#sec-Single-root-field
     """
 
     def enter_operation_definition(

src/graphql/validation/rules/unique_argument_names.py

@@ -12,6 +12,8 @@ class UniqueArgumentNamesRule(ASTValidationRule):
 
     A GraphQL field or directive is only valid if all supplied arguments are uniquely
     named.
+
+    See https://spec.graphql.org/draft/#sec-Argument-Names
     """
 
     def __init__(self, context: ASTValidationContext):

src/graphql/validation/rules/unique_directives_per_location.py

@@ -24,6 +24,8 @@ class UniqueDirectivesPerLocationRule(ASTValidationRule):
 
     A GraphQL document is only valid if all non-repeatable directives at a given
     location are uniquely named.
+
+    See https://spec.graphql.org/draft/#sec-Directives-Are-Unique-Per-Location
     """
 
     context: Union[ValidationContext, SDLValidationContext]

src/graphql/validation/rules/unique_fragment_names.py

@@ -11,6 +11,8 @@ class UniqueFragmentNamesRule(ASTValidationRule):
     """Unique fragment names
 
     A GraphQL document is only valid if all defined fragments have unique names.
+
+    See https://spec.graphql.org/draft/#sec-Fragment-Name-Uniqueness
     """
 
     def __init__(self, context: ASTValidationContext):

src/graphql/validation/rules/unique_input_field_names.py

@@ -12,6 +12,8 @@ class UniqueInputFieldNamesRule(ASTValidationRule):
 
     A GraphQL input object value is only valid if all supplied fields are uniquely
     named.
+
+    See https://spec.graphql.org/draft/#sec-Input-Object-Field-Uniqueness
     """
 
     def __init__(self, context: ASTValidationContext):

src/graphql/validation/rules/unique_operation_names.py

@@ -11,6 +11,8 @@ class UniqueOperationNamesRule(ASTValidationRule):
     """Unique operation names
 
     A GraphQL document is only valid if all defined operations have unique names.
+
+    See https://spec.graphql.org/draft/#sec-Operation-Name-Uniqueness
     """
 
     def __init__(self, context: ASTValidationContext):

src/graphql/validation/rules/values_of_correct_type.py

@@ -38,6 +38,8 @@ class ValuesOfCorrectTypeRule(ValidationRule):
 
     A GraphQL document is only valid if all value literals are of the type expected at
     their position.
+
+    See https://spec.graphql.org/draft/#sec-Values-of-Correct-Type
     """
 
     def enter_list_value(self, node: ListValueNode, *_args: Any) -> VisitorAction:

src/graphql/validation/rules/variables_are_input_types.py

@@ -14,6 +14,8 @@ class VariablesAreInputTypesRule(ValidationRule):
 
     A GraphQL operation is only valid if all the variables it defines are of input types
     (scalar, enum, or input object).
+
+    See https://spec.graphql.org/draft/#sec-Variables-Are-Input-Types
     """
 
     def enter_variable_definition(

src/graphql/validation/rules/variables_in_allowed_position.py

@@ -16,7 +16,12 @@
 
 
 class VariablesInAllowedPositionRule(ValidationRule):
-    """Variables passed to field arguments conform to type"""
+    """Variables in allowed position
+
+    Variable usages must be compatible with the arguments they are passed to.
+
+    See https://spec.graphql.org/draft/#sec-All-Variable-Usages-are-Allowed
+    """
 
     def __init__(self, context: ValidationContext):
         super().__init__(context)