docs(graphql): ensure descriptions for all mutation fields (#8346)

python_modules/dagster-graphql/dagster_graphql/schema/roots/mutation.py

@@ -596,7 +596,7 @@ def mutate(self, graphene_info, **kwargs):
 
 
 class GrapheneDagitMutation(graphene.ObjectType):
-    """Mutations to programatically interact with your Dagster instance."""
+    """The root for all mutations to modify data in your Dagster instance."""
 
     class Meta:
         name = "DagitMutation"

python_modules/dagster-graphql/dagster_graphql/schema/schedules/__init__.py

@@ -62,6 +62,8 @@ class Meta:
 
 
 class GrapheneStartScheduleMutation(graphene.Mutation):
+    """Enable a schedule to launch runs for a job at a fixed interval."""
+
     Output = graphene.NonNull(GrapheneScheduleMutationResult)
 
     class Arguments:
@@ -77,6 +79,8 @@ def mutate(self, graphene_info, schedule_selector):
 
 
 class GrapheneStopRunningScheduleMutation(graphene.Mutation):
+    """Disable a schedule from launching runs for a job."""
+
     Output = graphene.NonNull(GrapheneScheduleMutationResult)
 
     class Arguments:

python_modules/dagster-graphql/dagster_graphql/schema/sensors.py

@@ -123,6 +123,8 @@ class Meta:
 
 
 class GrapheneStartSensorMutation(graphene.Mutation):
+    """Enable a sensor to launch runs for a job based on external state change."""
+
     Output = graphene.NonNull(GrapheneSensorOrError)
 
     class Arguments:
@@ -160,6 +162,8 @@ class Meta:
 
 
 class GrapheneStopSensorMutation(graphene.Mutation):
+    """Disable a sensor from launching runs for a job."""
+
     Output = graphene.NonNull(GrapheneStopSensorMutationResultOrError)
 
     class Arguments:
@@ -176,6 +180,8 @@ def mutate(self, graphene_info, job_origin_id, job_selector_id):
 
 
 class GrapheneSetSensorCursorMutation(graphene.Mutation):
+    """Set a cursor for a sensor to track state across evaluations."""
+
     Output = graphene.NonNull(GrapheneSensorOrError)
 
     class Arguments:

python_modules/dagster-graphql/dagster_graphql_tests/test_schema.py

@@ -35,3 +35,40 @@ def test_schema_type_names_without_graphene(runner):
     assert (
         not violations
     ), f"'Graphene' cannot be included in the GraphQL type name. Violating types: {violations}."
+
+
+@pytest.mark.parametrize("operation_type", ["mutationType"])
+def test_schema_operation_fields_have_descriptions(runner, operation_type):
+    query = f"""
+    query GetOperationFieldDescriptions {{
+        __schema {{
+            {operation_type} {{
+                name
+                description
+                fields {{
+                    name
+                    description
+                }}
+            }}
+        }}
+    }}
+    """
+
+    result = runner.invoke(
+        ui,
+        ["--empty-workspace", "--ephemeral-instance", "-t", query],
+    )
+    operation_type_root = json.loads(result.output)["data"]["__schema"][operation_type]
+
+    assert operation_type_root[
+        "description"
+    ], f"Operation root '{operation_type_root['name']}' for '{operation_type}' must have a description."
+
+    violations = [
+        operation_field_type["name"]
+        for operation_field_type in operation_type_root["fields"]
+        if not operation_field_type["description"]
+    ]
+    assert (
+        not violations
+    ), f"Descriptions must be included in the GraphQL '{operation_type}' fields. Violating types: {violations}."