Improve documentation of validation rules (#3285)

* Added missing documentation
* Added links to GraphQL spec

Author: IvanGoncharov

src/validation/rules/ExecutableDefinitionsRule.ts

@@ -11,6 +11,8 @@ import type { ASTValidationContext } from '../ValidationContext';
  *
  * 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
  */
 export function ExecutableDefinitionsRule(
   context: ASTValidationContext,

src/validation/rules/FieldsOnCorrectTypeRule.ts

@@ -26,6 +26,8 @@ import type { ValidationContext } from '../ValidationContext';
  *
  * 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
  */
 export function FieldsOnCorrectTypeRule(
   context: ValidationContext,

src/validation/rules/FragmentsOnCompositeTypesRule.ts

@@ -15,6 +15,8 @@ import type { ValidationContext } from '../ValidationContext';
  * 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
  */
 export function FragmentsOnCompositeTypesRule(
   context: ValidationContext,

src/validation/rules/KnownArgumentNamesRule.ts

@@ -18,6 +18,9 @@ import type {
  *
  * 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
  */
 export function KnownArgumentNamesRule(context: ValidationContext): ASTVisitor {
   return {

src/validation/rules/KnownDirectivesRule.ts

@@ -21,6 +21,8 @@ import type {
  *
  * 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
  */
 export function KnownDirectivesRule(
   context: ValidationContext | SDLValidationContext,

src/validation/rules/KnownFragmentNamesRule.ts

@@ -9,6 +9,8 @@ import type { ValidationContext } from '../ValidationContext';
  *
  * 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
  */
 export function KnownFragmentNamesRule(context: ValidationContext): ASTVisitor {
   return {

src/validation/rules/KnownTypeNamesRule.ts

@@ -24,6 +24,8 @@ import type {
  *
  * 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
  */
 export function KnownTypeNamesRule(
   context: ValidationContext | SDLValidationContext,

src/validation/rules/LoneAnonymousOperationRule.ts

@@ -10,6 +10,8 @@ import type { ASTValidationContext } from '../ValidationContext';
  *
  * 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
  */
 export function LoneAnonymousOperationRule(
   context: ASTValidationContext,

src/validation/rules/NoFragmentCyclesRule.ts

@@ -10,6 +10,14 @@ import type { ASTVisitor } from '../../language/visitor';
 
 import type { ASTValidationContext } from '../ValidationContext';
 
+/**
+ * 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
+ */
 export function NoFragmentCyclesRule(
   context: ASTValidationContext,
 ): ASTVisitor {

src/validation/rules/NoUndefinedVariablesRule.ts

@@ -9,6 +9,8 @@ import type { ValidationContext } from '../ValidationContext';
  *
  * 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
  */
 export function NoUndefinedVariablesRule(
   context: ValidationContext,

src/validation/rules/NoUnusedFragmentsRule.ts

@@ -13,6 +13,8 @@ import type { ASTValidationContext } from '../ValidationContext';
  *
  * 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
  */
 export function NoUnusedFragmentsRule(
   context: ASTValidationContext,

src/validation/rules/NoUnusedVariablesRule.ts

@@ -10,6 +10,8 @@ import type { ValidationContext } from '../ValidationContext';
  *
  * 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
  */
 export function NoUnusedVariablesRule(context: ValidationContext): ASTVisitor {
   let variableDefs: Array<VariableDefinitionNode> = [];

src/validation/rules/OverlappingFieldsCanBeMergedRule.ts

@@ -53,6 +53,8 @@ function reasonMessage(reason: ConflictReasonMessage): string {
  * 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-Merging
  */
 export function OverlappingFieldsCanBeMergedRule(
   context: ValidationContext,

src/validation/rules/SingleFieldSubscriptionsRule.ts

@@ -17,6 +17,8 @@ import type { ValidationContext } from '../ValidationContext';
  *
  * 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
  */
 export function SingleFieldSubscriptionsRule(
   context: ValidationContext,

src/validation/rules/UniqueArgumentNamesRule.ts

@@ -8,6 +8,8 @@ import type { ASTValidationContext } from '../ValidationContext';
  *
  * A GraphQL field or directive is only valid if all supplied arguments are
  * uniquely named.
+ *
+ * See https://spec.graphql.org/draft/#sec-Argument-Names
  */
 export function UniqueArgumentNamesRule(
   context: ASTValidationContext,

src/validation/rules/UniqueDirectivesPerLocationRule.ts

@@ -19,6 +19,8 @@ import type {
  *
  * 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
  */
 export function UniqueDirectivesPerLocationRule(
   context: ValidationContext | SDLValidationContext,

src/validation/rules/UniqueFragmentNamesRule.ts

@@ -8,6 +8,8 @@ import type { ASTValidationContext } from '../ValidationContext';
  * 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
  */
 export function UniqueFragmentNamesRule(
   context: ASTValidationContext,

src/validation/rules/UniqueInputFieldNamesRule.ts

@@ -13,6 +13,8 @@ import type { ASTValidationContext } from '../ValidationContext';
  *
  * 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
  */
 export function UniqueInputFieldNamesRule(
   context: ASTValidationContext,

src/validation/rules/UniqueOperationNamesRule.ts

@@ -8,6 +8,8 @@ import type { ASTValidationContext } from '../ValidationContext';
  * 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
  */
 export function UniqueOperationNamesRule(
   context: ASTValidationContext,

src/validation/rules/ValuesOfCorrectTypeRule.ts

@@ -26,6 +26,8 @@ import type { ValidationContext } from '../ValidationContext';
  *
  * 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
  */
 export function ValuesOfCorrectTypeRule(
   context: ValidationContext,

src/validation/rules/VariablesAreInputTypesRule.ts

@@ -15,6 +15,8 @@ import type { ValidationContext } from '../ValidationContext';
  *
  * 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
  */
 export function VariablesAreInputTypesRule(
   context: ValidationContext,

src/validation/rules/VariablesInAllowedPositionRule.ts

@@ -17,7 +17,11 @@ import { isTypeSubTypeOf } from '../../utilities/typeComparators';
 import type { ValidationContext } from '../ValidationContext';
 
 /**
- * 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
  */
 export function VariablesInAllowedPositionRule(
   context: ValidationContext,