Merge branch 'docs-cablett-graphql-headings' into 'master'

Show Graphql type descriptions

See merge request gitlab-org/gitlab!22568

app/graphql/types/award_emojis/award_emoji_type.rb

@@ -4,6 +4,7 @@ module Types
   module AwardEmojis
     class AwardEmojiType < BaseObject
       graphql_name 'AwardEmoji'
+      description 'An emoji awarded by a user.'
 
       authorize :read_emoji
 

doc/api/graphql/reference/gitlab_schema.graphql

@@ -38,6 +38,9 @@ type AddAwardEmojiPayload {
   errors: [String!]!
 }
 
+"""
+An emoji awarded by a user.
+"""
 type AwardEmoji {
   """
   The emoji description
@@ -529,6 +532,9 @@ type CreateSnippetPayload {
   snippet: Snippet
 }
 
+"""
+A single design
+"""
 type Design implements DesignFields & Noteable {
   """
   The diff refs for this design
@@ -651,6 +657,9 @@ type Design implements DesignFields & Noteable {
   ): DesignVersionConnection!
 }
 
+"""
+A collection of designs.
+"""
 type DesignCollection {
   """
   All designs for the design collection
@@ -979,7 +988,7 @@ type DesignVersionEdge {
 }
 
 """
-Mutation event of a Design within a Version
+Mutation event of a design within a version
 """
 enum DesignVersionEvent {
   """
@@ -1403,6 +1412,9 @@ enum EntryType {
   tree
 }
 
+"""
+Represents an epic.
+"""
 type Epic implements Noteable {
   """
   Author of the epic
@@ -1761,6 +1773,9 @@ type EpicConnection {
   pageInfo: PageInfo!
 }
 
+"""
+Counts of descendent epics.
+"""
 type EpicDescendantCount {
   """
   Number of closed sub-epics
@@ -1798,6 +1813,9 @@ type EpicEdge {
   node: Epic
 }
 
+"""
+Relationship between an epic and an issue
+"""
 type EpicIssue implements Noteable {
   """
   Assignees of the issue
@@ -2246,7 +2264,7 @@ enum EpicSort {
 }
 
 """
-State of a GitLab epic
+State of an epic.
 """
 enum EpicState {
   all
@@ -2255,20 +2273,23 @@ enum EpicState {
 }
 
 """
-State event of a GitLab Epic
+State event of an epic
 """
 enum EpicStateEvent {
   """
-  Close the Epic
+  Close the epic
   """
   CLOSE
 
   """
-  Reopen the Epic
+  Reopen the epic
   """
   REOPEN
 }
 
+"""
+A node of an epic tree.
+"""
 input EpicTreeNodeFieldsInputType {
   """
   The id of the epic_issue or issue that the actual epic or issue is switched with

doc/api/graphql/reference/gitlab_schema.json

@@ -3695,7 +3695,7 @@
         {
           "kind": "OBJECT",
           "name": "Epic",
-          "description": null,
+          "description": "Represents an epic.",
           "fields": [
             {
               "name": "author",
@@ -7384,7 +7384,7 @@
         {
           "kind": "ENUM",
           "name": "EpicState",
-          "description": "State of a GitLab epic",
+          "description": "State of an epic.",
           "fields": null,
           "inputFields": null,
           "interfaces": null,
@@ -8009,7 +8009,7 @@
         {
           "kind": "OBJECT",
           "name": "EpicIssue",
-          "description": null,
+          "description": "Relationship between an epic and an issue",
           "fields": [
             {
               "name": "assignees",
@@ -9230,7 +9230,7 @@
         {
           "kind": "OBJECT",
           "name": "DesignCollection",
-          "description": null,
+          "description": "A collection of designs.",
           "fields": [
             {
               "name": "designs",
@@ -10346,7 +10346,7 @@
         {
           "kind": "OBJECT",
           "name": "Design",
-          "description": null,
+          "description": "A single design",
           "fields": [
             {
               "name": "diffRefs",
@@ -10880,7 +10880,7 @@
         {
           "kind": "ENUM",
           "name": "DesignVersionEvent",
-          "description": "Mutation event of a Design within a Version",
+          "description": "Mutation event of a design within a version",
           "fields": null,
           "inputFields": null,
           "interfaces": null,
@@ -11133,7 +11133,7 @@
         {
           "kind": "OBJECT",
           "name": "EpicDescendantCount",
-          "description": null,
+          "description": "Counts of descendent epics.",
           "fields": [
             {
               "name": "closedEpics",
@@ -16943,7 +16943,7 @@
         {
           "kind": "OBJECT",
           "name": "AwardEmoji",
-          "description": null,
+          "description": "An emoji awarded by a user.",
           "fields": [
             {
               "name": "description",
@@ -20689,7 +20689,7 @@
         {
           "kind": "INPUT_OBJECT",
           "name": "EpicTreeNodeFieldsInputType",
-          "description": null,
+          "description": "A node of an epic tree.",
           "fields": null,
           "inputFields": [
             {
@@ -20987,20 +20987,20 @@
         {
           "kind": "ENUM",
           "name": "EpicStateEvent",
-          "description": "State event of a GitLab Epic",
+          "description": "State event of an epic",
           "fields": null,
           "inputFields": null,
           "interfaces": null,
           "enumValues": [
             {
               "name": "REOPEN",
-              "description": "Reopen the Epic",
+              "description": "Reopen the epic",
               "isDeprecated": false,
               "deprecationReason": null
             },
             {
               "name": "CLOSE",
-              "description": "Close the Epic",
+              "description": "Close the epic",
               "isDeprecated": false,
               "deprecationReason": null
             }

doc/api/graphql/reference/index.md

@@ -9,10 +9,12 @@
 This documentation is self-generated based on GitLab current GraphQL schema.
 
 The API can be explored interactively using the [GraphiQL IDE](../index.md#graphiql).
+Each table below documents a GraphQL type. Types match loosely to models, but not all
+fields and methods on a model are available via GraphQL.
 
-## Objects
+## AddAwardEmojiPayload
 
-### AddAwardEmojiPayload
+Autogenerated return type of AddAwardEmoji
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -20,7 +22,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `errors` | String! => Array | Reasons why the mutation failed. |
 | `awardEmoji` | AwardEmoji | The award emoji after mutation |
 
-### AwardEmoji
+## AwardEmoji
+
+An emoji awarded by a user.
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -31,7 +35,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `unicodeVersion` | String! | The unicode version for this emoji |
 | `user` | User! | The user who awarded the emoji |
 
-### Blob
+## Blob
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -44,7 +48,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `webUrl` | String | Web URL of the blob |
 | `lfsOid` | String | LFS ID of the blob |
 
-### Commit
+## Commit
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -60,7 +64,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `author` | User | Author of the commit |
 | `latestPipeline` | Pipeline | Latest pipeline of the commit |
 
-### CreateDiffNotePayload
+## CreateDiffNotePayload
+
+Autogenerated return type of CreateDiffNote
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -68,7 +74,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `errors` | String! => Array | Reasons why the mutation failed. |
 | `note` | Note | The note after mutation |
 
-### CreateEpicPayload
+## CreateEpicPayload
+
+Autogenerated return type of CreateEpic
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -76,7 +84,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `errors` | String! => Array | Reasons why the mutation failed. |
 | `epic` | Epic | The created epic |
 
-### CreateImageDiffNotePayload
+## CreateImageDiffNotePayload
+
+Autogenerated return type of CreateImageDiffNote
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -84,7 +94,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `errors` | String! => Array | Reasons why the mutation failed. |
 | `note` | Note | The note after mutation |
 
-### CreateNotePayload
+## CreateNotePayload
+
+Autogenerated return type of CreateNote
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -92,7 +104,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `errors` | String! => Array | Reasons why the mutation failed. |
 | `note` | Note | The note after mutation |
 
-### CreateSnippetPayload
+## CreateSnippetPayload
+
+Autogenerated return type of CreateSnippet
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -100,7 +114,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `errors` | String! => Array | Reasons why the mutation failed. |
 | `snippet` | Snippet | The snippet after mutation |
 
-### Design
+## Design
+
+A single design
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -114,14 +130,18 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `event` | DesignVersionEvent! | How this design was changed in the current version |
 | `notesCount` | Int! | The total count of user-created notes for this design |
 
-### DesignCollection
+## DesignCollection
+
+A collection of designs.
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
 | `project` | Project! | Project associated with the design collection |
 | `issue` | Issue! | Issue associated with the design collection |
 
-### DesignManagementDeletePayload
+## DesignManagementDeletePayload
+
+Autogenerated return type of DesignManagementDelete
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -129,7 +149,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `errors` | String! => Array | Reasons why the mutation failed. |
 | `version` | DesignVersion | The new version in which the designs are deleted |
 
-### DesignManagementUploadPayload
+## DesignManagementUploadPayload
+
+Autogenerated return type of DesignManagementUpload
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -138,14 +160,16 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `designs` | Design! => Array | The designs that were uploaded by the mutation |
 | `skippedDesigns` | Design! => Array | Any designs that were skipped from the upload due to there being no change to their content since their last version |
 
-### DesignVersion
+## DesignVersion
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
 | `id` | ID! | ID of the design version |
 | `sha` | ID! | SHA of the design version |
 
-### DestroyNotePayload
+## DestroyNotePayload
+
+Autogenerated return type of DestroyNote
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -153,7 +177,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `errors` | String! => Array | Reasons why the mutation failed. |
 | `note` | Note | The note after mutation |
 
-### DestroySnippetPayload
+## DestroySnippetPayload
+
+Autogenerated return type of DestroySnippet
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -161,7 +187,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `errors` | String! => Array | Reasons why the mutation failed. |
 | `snippet` | Snippet | The snippet after mutation |
 
-### DetailedStatus
+## DetailedStatus
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -174,7 +200,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `text` | String! | Text of the pipeline status |
 | `tooltip` | String! | Tooltip associated with the pipeline status |
 
-### DiffPosition
+## DiffPosition
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -190,7 +216,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `width` | Int | Total width of the image |
 | `height` | Int | Total height of the image |
 
-### DiffRefs
+## DiffRefs
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -198,7 +224,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `baseSha` | String! | Merge base of the branch the comment was made on |
 | `startSha` | String! | SHA of the branch being compared against |
 
-### Discussion
+## Discussion
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -206,7 +232,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `replyId` | ID! | ID used to reply to this discussion |
 | `createdAt` | Time! | Timestamp of the discussion's creation |
 
-### Epic
+## Epic
+
+Represents an epic.
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -242,7 +270,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `subscribed` | Boolean! | Indicates the currently logged in user is subscribed to the epic |
 | `descendantCounts` | EpicDescendantCount | Number of open and closed descendant epics and issues |
 
-### EpicDescendantCount
+## EpicDescendantCount
+
+Counts of descendent epics.
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -251,7 +281,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `openedIssues` | Int | Number of opened epic issues |
 | `closedIssues` | Int | Number of closed epic issues |
 
-### EpicIssue
+## EpicIssue
+
+Relationship between an epic and an issue
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -289,7 +321,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `relationPath` | String | URI path of the epic-issue relation |
 | `id` | ID | Global ID of the epic-issue relation |
 
-### EpicPermissions
+## EpicPermissions
+
+Check permissions for the current user on an epic
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -302,7 +336,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `createNote` | Boolean! | Indicates the user can perform `create_note` on this resource |
 | `awardEmoji` | Boolean! | Indicates the user can perform `award_emoji` on this resource |
 
-### EpicSetSubscriptionPayload
+## EpicSetSubscriptionPayload
+
+Autogenerated return type of EpicSetSubscription
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -310,14 +346,16 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `errors` | String! => Array | Reasons why the mutation failed. |
 | `epic` | Epic | The epic after mutation |
 
-### EpicTreeReorderPayload
+## EpicTreeReorderPayload
+
+Autogenerated return type of EpicTreeReorder
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
 | `clientMutationId` | String | A unique identifier for the client performing the mutation. |
 | `errors` | String! => Array | Reasons why the mutation failed. |
 
-### GrafanaIntegration
+## GrafanaIntegration
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -328,7 +366,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `createdAt` | Time! | Timestamp of the issue's creation |
 | `updatedAt` | Time! | Timestamp of the issue's last activity |
 
-### Group
+## Group
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -351,13 +389,13 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `groupTimelogsEnabled` | Boolean | Indicates if Group timelogs are enabled for namespace |
 | `epic` | Epic | Find a single epic |
 
-### GroupPermissions
+## GroupPermissions
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
 | `readGroup` | Boolean! | Indicates the user can perform `read_group` on this resource |
 
-### Issue
+## Issue
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -392,7 +430,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `designs` | DesignCollection | Deprecated. Use `design_collection` |
 | `designCollection` | DesignCollection | Collection of design images associated with this issue |
 
-### IssuePermissions
+## IssuePermissions
+
+Check permissions for the current user on a issue
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -405,7 +445,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `createDesign` | Boolean! | Indicates the user can perform `create_design` on this resource |
 | `destroyDesign` | Boolean! | Indicates the user can perform `destroy_design` on this resource |
 
-### IssueSetConfidentialPayload
+## IssueSetConfidentialPayload
+
+Autogenerated return type of IssueSetConfidential
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -413,7 +455,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `errors` | String! => Array | Reasons why the mutation failed. |
 | `issue` | Issue | The issue after mutation |
 
-### IssueSetDueDatePayload
+## IssueSetDueDatePayload
+
+Autogenerated return type of IssueSetDueDate
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -421,7 +465,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `errors` | String! => Array | Reasons why the mutation failed. |
 | `issue` | Issue | The issue after mutation |
 
-### IssueSetWeightPayload
+## IssueSetWeightPayload
+
+Autogenerated return type of IssueSetWeight
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -429,7 +475,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `errors` | String! => Array | Reasons why the mutation failed. |
 | `issue` | Issue | The issue after mutation |
 
-### Label
+## Label
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -440,7 +486,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `color` | String! | Background color of the label |
 | `textColor` | String! | Text color of the label |
 
-### MarkAsSpamSnippetPayload
+## MarkAsSpamSnippetPayload
+
+Autogenerated return type of MarkAsSpamSnippet
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -448,7 +496,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `errors` | String! => Array | Reasons why the mutation failed. |
 | `snippet` | Snippet | The snippet after mutation |
 
-### MergeRequest
+## MergeRequest
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -502,7 +550,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `reference` | String! | Internal reference of the merge request. Returned in shortened format by default |
 | `taskCompletionStatus` | TaskCompletionStatus! | Completion status of tasks |
 
-### MergeRequestPermissions
+## MergeRequestPermissions
+
+Check permissions for the current user on a merge request
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -515,7 +565,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `cherryPickOnCurrentMergeRequest` | Boolean! | Indicates the user can perform `cherry_pick_on_current_merge_request` on this resource |
 | `revertOnCurrentMergeRequest` | Boolean! | Indicates the user can perform `revert_on_current_merge_request` on this resource |
 
-### MergeRequestSetAssigneesPayload
+## MergeRequestSetAssigneesPayload
+
+Autogenerated return type of MergeRequestSetAssignees
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -523,7 +575,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `errors` | String! => Array | Reasons why the mutation failed. |
 | `mergeRequest` | MergeRequest | The merge request after mutation |
 
-### MergeRequestSetLabelsPayload
+## MergeRequestSetLabelsPayload
+
+Autogenerated return type of MergeRequestSetLabels
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -531,7 +585,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `errors` | String! => Array | Reasons why the mutation failed. |
 | `mergeRequest` | MergeRequest | The merge request after mutation |
 
-### MergeRequestSetLockedPayload
+## MergeRequestSetLockedPayload
+
+Autogenerated return type of MergeRequestSetLocked
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -539,7 +595,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `errors` | String! => Array | Reasons why the mutation failed. |
 | `mergeRequest` | MergeRequest | The merge request after mutation |
 
-### MergeRequestSetMilestonePayload
+## MergeRequestSetMilestonePayload
+
+Autogenerated return type of MergeRequestSetMilestone
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -547,7 +605,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `errors` | String! => Array | Reasons why the mutation failed. |
 | `mergeRequest` | MergeRequest | The merge request after mutation |
 
-### MergeRequestSetSubscriptionPayload
+## MergeRequestSetSubscriptionPayload
+
+Autogenerated return type of MergeRequestSetSubscription
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -555,7 +615,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `errors` | String! => Array | Reasons why the mutation failed. |
 | `mergeRequest` | MergeRequest | The merge request after mutation |
 
-### MergeRequestSetWipPayload
+## MergeRequestSetWipPayload
+
+Autogenerated return type of MergeRequestSetWip
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -563,14 +625,14 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `errors` | String! => Array | Reasons why the mutation failed. |
 | `mergeRequest` | MergeRequest | The merge request after mutation |
 
-### Metadata
+## Metadata
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
 | `version` | String! | Version |
 | `revision` | String! | Revision |
 
-### Milestone
+## Milestone
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -583,7 +645,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `createdAt` | Time! | Timestamp of milestone creation |
 | `updatedAt` | Time! | Timestamp of last milestone update |
 
-### Namespace
+## Namespace
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -599,7 +661,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `requestAccessEnabled` | Boolean | Indicates if users can request access to namespace |
 | `rootStorageStatistics` | RootStorageStatistics | Aggregated storage statistics of the namespace. Only available for root namespaces |
 
-### Note
+## Note
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -618,7 +680,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `resolvedAt` | Time | Timestamp of the note's resolution |
 | `position` | DiffPosition | The position of this note on a diff |
 
-### NotePermissions
+## NotePermissions
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -628,7 +690,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `resolveNote` | Boolean! | Indicates the user can perform `resolve_note` on this resource |
 | `awardEmoji` | Boolean! | Indicates the user can perform `award_emoji` on this resource |
 
-### PageInfo
+## PageInfo
+
+Information about pagination in a connection.
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -637,7 +701,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `startCursor` | String | When paginating backwards, the cursor to continue. |
 | `endCursor` | String | When paginating forwards, the cursor to continue. |
 
-### Pipeline
+## Pipeline
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -656,7 +720,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `finishedAt` | Time | Timestamp of the pipeline's completion |
 | `committedAt` | Time | Timestamp of the pipeline's commit |
 
-### PipelinePermissions
+## PipelinePermissions
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -664,7 +728,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `adminPipeline` | Boolean! | Indicates the user can perform `admin_pipeline` on this resource |
 | `destroyPipeline` | Boolean! | Indicates the user can perform `destroy_pipeline` on this resource |
 
-### Project
+## Project
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -716,7 +780,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `serviceDeskEnabled` | Boolean | Indicates if the project has service desk enabled. |
 | `serviceDeskAddress` | String | E-mail address of the service desk. |
 
-### ProjectPermissions
+## ProjectPermissions
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -762,7 +826,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `createDesign` | Boolean! | Indicates the user can perform `create_design` on this resource |
 | `destroyDesign` | Boolean! | Indicates the user can perform `destroy_design` on this resource |
 
-### ProjectStatistics
+## ProjectStatistics
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -774,7 +838,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `packagesSize` | Int! | Packages size of the project |
 | `wikiSize` | Int | Wiki size of the project |
 
-### RemoveAwardEmojiPayload
+## RemoveAwardEmojiPayload
+
+Autogenerated return type of RemoveAwardEmoji
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -782,7 +848,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `errors` | String! => Array | Reasons why the mutation failed. |
 | `awardEmoji` | AwardEmoji | The award emoji after mutation |
 
-### Repository
+## Repository
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -791,7 +857,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `exists` | Boolean! | Indicates a corresponding Git repository exists on disk |
 | `tree` | Tree | Tree of the repository |
 
-### RootStorageStatistics
+## RootStorageStatistics
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -802,7 +868,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `packagesSize` | Int! | The packages size in bytes |
 | `wikiSize` | Int! | The wiki size in bytes |
 
-### SentryDetailedError
+## SentryDetailedError
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -828,14 +894,16 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `firstReleaseShortVersion` | String | Release version the error was first seen |
 | `lastReleaseShortVersion` | String | Release version the error was last seen |
 
-### SentryErrorFrequency
+## SentryErrorFrequency
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
 | `time` | Time! | Time the error frequency stats were recorded |
 | `count` | Int! | Count of errors received since the previously recorded time |
 
-### Snippet
+## Snippet
+
+Represents a snippet entry
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -854,7 +922,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `rawUrl` | String! | Raw URL of the snippet |
 | `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` |
 
-### SnippetPermissions
+## SnippetPermissions
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -865,7 +933,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `adminSnippet` | Boolean! | Indicates the user can perform `admin_snippet` on this resource |
 | `reportSnippet` | Boolean! | Indicates the user can perform `report_snippet` on this resource |
 
-### Submodule
+## Submodule
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -878,14 +946,16 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `webUrl` | String | Web URL for the sub-module |
 | `treeUrl` | String | Tree URL for the sub-module |
 
-### TaskCompletionStatus
+## TaskCompletionStatus
+
+Completion status of tasks
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
 | `count` | Int! | Number of total tasks |
 | `completedCount` | Int! | Number of completed tasks |
 
-### Timelog
+## Timelog
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -894,7 +964,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `user` | User! | The user that logged the time |
 | `issue` | Issue | The issue that logged time was added to |
 
-### Todo
+## Todo
+
+Representing a todo entry
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -908,7 +980,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `state` | TodoStateEnum! | State of the todo |
 | `createdAt` | Time! | Timestamp this todo was created |
 
-### TodoMarkDonePayload
+## TodoMarkDonePayload
+
+Autogenerated return type of TodoMarkDone
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -916,7 +990,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `errors` | String! => Array | Reasons why the mutation failed. |
 | `todo` | Todo! | The requested todo |
 
-### TodoRestorePayload
+## TodoRestorePayload
+
+Autogenerated return type of TodoRestore
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -924,7 +1000,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `errors` | String! => Array | Reasons why the mutation failed. |
 | `todo` | Todo! | The requested todo |
 
-### TodosMarkAllDonePayload
+## TodosMarkAllDonePayload
+
+Autogenerated return type of TodosMarkAllDone
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -932,7 +1010,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `errors` | String! => Array | Reasons why the mutation failed. |
 | `updatedIds` | ID! => Array | Ids of the updated todos |
 
-### ToggleAwardEmojiPayload
+## ToggleAwardEmojiPayload
+
+Autogenerated return type of ToggleAwardEmoji
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -941,13 +1021,15 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `awardEmoji` | AwardEmoji | The award emoji after mutation |
 | `toggledOn` | Boolean! | Indicates the status of the emoji. True if the toggle awarded the emoji, and false if the toggle removed the emoji. |
 
-### Tree
+## Tree
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
 | `lastCommit` | Commit | Last commit for the tree |
 
-### TreeEntry
+## TreeEntry
+
+Represents a directory
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -959,7 +1041,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `flatPath` | String! | Flat path of the entry |
 | `webUrl` | String | Web URL for the tree entry (directory) |
 
-### UpdateEpicPayload
+## UpdateEpicPayload
+
+Autogenerated return type of UpdateEpic
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -967,7 +1051,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `errors` | String! => Array | Reasons why the mutation failed. |
 | `epic` | Epic | The epic after mutation |
 
-### UpdateNotePayload
+## UpdateNotePayload
+
+Autogenerated return type of UpdateNote
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -975,7 +1061,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `errors` | String! => Array | Reasons why the mutation failed. |
 | `note` | Note | The note after mutation |
 
-### UpdateSnippetPayload
+## UpdateSnippetPayload
+
+Autogenerated return type of UpdateSnippet
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -983,7 +1071,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `errors` | String! => Array | Reasons why the mutation failed. |
 | `snippet` | Snippet | The snippet after mutation |
 
-### User
+## User
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
@@ -993,7 +1081,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `avatarUrl` | String! | URL of the user's avatar |
 | `webUrl` | String! | Web URL of the user |
 
-### UserPermissions
+## UserPermissions
 
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |

ee/app/graphql/types/design_management/design_collection_type.rb

@@ -4,6 +4,7 @@ module Types
   module DesignManagement
     class DesignCollectionType < BaseObject
       graphql_name 'DesignCollection'
+      description 'A collection of designs.'
 
       authorize :read_design
 

ee/app/graphql/types/design_management/design_type.rb

@@ -4,6 +4,7 @@ module Types
   module DesignManagement
     class DesignType < BaseObject
       graphql_name 'Design'
+      description 'A single design'
 
       authorize :read_design
 

ee/app/graphql/types/design_management/design_version_event_enum.rb

@@ -4,7 +4,7 @@ module Types
   module DesignManagement
     class DesignVersionEventEnum < BaseEnum
       graphql_name 'DesignVersionEvent'
-      description 'Mutation event of a Design within a Version'
+      description 'Mutation event of a design within a version'
 
       NONE = 'NONE'
 

ee/app/graphql/types/epic_descendant_count_type.rb

@@ -4,6 +4,7 @@ module Types
   # rubocop: disable Graphql/AuthorizeTypes
   class EpicDescendantCountType < BaseObject
     graphql_name 'EpicDescendantCount'
+    description 'Counts of descendent epics.'
 
     field :opened_epics, GraphQL::INT_TYPE, null: true, description: 'Number of opened sub-epics'
     field :closed_epics, GraphQL::INT_TYPE, null: true, description: 'Number of closed sub-epics'

ee/app/graphql/types/epic_issue_type.rb

@@ -5,6 +5,7 @@ module Types
   # This is a subclass of `IssueType` which has authorization
   class EpicIssueType < IssueType
     graphql_name 'EpicIssue'
+    description 'Relationship between an epic and an issue'
 
     present_using EpicIssuePresenter
 

ee/app/graphql/types/epic_state_enum.rb

@@ -3,7 +3,7 @@
 module Types
   class EpicStateEnum < BaseEnum
     graphql_name 'EpicState'
-    description 'State of a GitLab epic'
+    description 'State of an epic.'
 
     value 'all'
     value 'opened'

ee/app/graphql/types/epic_state_event_enum.rb

@@ -3,9 +3,9 @@
 module Types
   class EpicStateEventEnum < BaseEnum
     graphql_name 'EpicStateEvent'
-    description 'State event of a GitLab Epic'
+    description 'State event of an epic'
 
-    value 'REOPEN', value: 'reopen', description: 'Reopen the Epic'
-    value 'CLOSE', value: 'close', description: 'Close the Epic'
+    value 'REOPEN', value: 'reopen', description: 'Reopen the epic'
+    value 'CLOSE', value: 'close', description: 'Close the epic'
   end
 end

ee/app/graphql/types/epic_tree/epic_tree_node_input_type.rb

@@ -5,6 +5,7 @@ module Types
     # rubocop: disable Graphql/AuthorizeTypes
     class EpicTreeNodeInputType < BaseInputObject
       graphql_name 'EpicTreeNodeFieldsInputType'
+      description 'A node of an epic tree.'
 
       MoveTypeEnum = GraphQL::EnumType.define do
         name 'MoveType'

ee/app/graphql/types/epic_type.rb

@@ -3,6 +3,7 @@
 module Types
   class EpicType < BaseObject
     graphql_name 'Epic'
+    description 'Represents an epic.'
 
     authorize :read_epic
 

ee/app/graphql/types/permission_types/epic.rb

@@ -3,8 +3,8 @@
 module Types
   module PermissionTypes
     class Epic < BasePermissionType
-      description 'Check permissions for the current user on an epic'
       graphql_name 'EpicPermissions'
+      description 'Check permissions for the current user on an epic'
 
       abilities :read_epic, :read_epic_iid, :update_epic, :destroy_epic, :admin_epic,
                 :create_epic, :create_note, :award_emoji

lib/gitlab/graphql/docs/renderer.rb

@@ -10,7 +10,7 @@ module Gitlab
       # It uses graphql-docs helpers and schema parser, more information in https://github.com/gjtorikian/graphql-docs.
       #
       # Arguments:
-      #   schema - the GraphQL schema defition. For GitLab should be: GitlabSchema.graphql_definition
+      #   schema - the GraphQL schema definition. For GitLab should be: GitlabSchema.graphql_definition
       #   output_dir: The folder where the markdown files will be saved
       #   template: The path of the haml template to be parsed
       class Renderer

lib/gitlab/graphql/docs/templates/default.md.haml

@@ -9,11 +9,15 @@
 
   The API can be explored interactively using the [GraphiQL IDE](../index.md#graphiql).
 
-  ## Objects
+Each table below documents a GraphQL type. Types match loosely to models, but not all
+fields and methods on a model are available via GraphQL.
 \
 - objects.each do |type|
   - unless type[:fields].empty?
-    = "### #{type[:name]}"
+    = "## #{type[:name]}"
+    - if type[:description]&.present?
+      \
+      = type[:description]
     \
     ~ "| Name  | Type  | Description |"
     ~ "| ---   |  ---- | ----------  |"