Merge branch 'cablett-backfilling-part-2-docs' into 'master'

Backfill GraphQL epic type descriptions (part 2)

See merge request gitlab-org/gitlab!21164

doc/api/graphql/reference/gitlab_schema.graphql

@@ -1128,7 +1128,14 @@ enum EntryType {
 }
 
 type Epic implements Noteable {
+  """
+  Author of the epic
+  """
   author: User!
+
+  """
+  Children (sub-epics) of the epic
+  """
   children(
     """
     Returns the elements in the list that come after the specified cursor.
@@ -1197,13 +1204,25 @@ type Epic implements Noteable {
     """
     state: EpicState
   ): EpicConnection
+
+  """
+  Timestamp of the epic's closure
+  """
   closedAt: Time
+
+  """
+  Timestamp of the epic's creation
+  """
   createdAt: Time
 
   """
   Number of open and closed descendant epics and issues
   """
   descendantCounts: EpicDescendantCount
+
+  """
+  Description of the epic
+  """
   description: String
 
   """
@@ -1235,14 +1254,50 @@ type Epic implements Noteable {
   Number of downvotes the epic has received
   """
   downvotes: Int!
+
+  """
+  Due date of the epic
+  """
   dueDate: Time
+
+  """
+  Fixed due date of the epic
+  """
   dueDateFixed: Time
+
+  """
+  Inherited due date of the epic from milestones
+  """
   dueDateFromMilestones: Time
+
+  """
+  Indicates if the due date has been manually set
+  """
   dueDateIsFixed: Boolean
+
+  """
+  Group to which the epic belongs
+  """
   group: Group!
+
+  """
+  Indicates if the epic has children
+  """
   hasChildren: Boolean!
+
+  """
+  Indicates if the epic has direct issues
+  """
   hasIssues: Boolean!
+
+  """
+  ID of the epic
+  """
   id: ID!
+
+  """
+  Internal ID of the epic
+  """
   iid: ID!
 
   """
@@ -1319,6 +1374,10 @@ type Epic implements Noteable {
     """
     last: Int
   ): NoteConnection!
+
+  """
+  Parent epic of the epic
+  """
   parent: Epic
 
   """
@@ -1349,20 +1408,48 @@ type Epic implements Noteable {
   relationPath: String
 
   """
-  The relative position of the epic in the Epic tree
+  The relative position of the epic in the epic tree
   """
   relativePosition: Int
+
+  """
+  Start date of the epic
+  """
   startDate: Time
+
+  """
+  Fixed start date of the epic
+  """
   startDateFixed: Time
+
+  """
+  Inherited start date of the epic from milestones
+  """
   startDateFromMilestones: Time
+
+  """
+  Indicates if the start date has been manually set
+  """
   startDateIsFixed: Boolean
+
+  """
+  State of the epic
+  """
   state: EpicState!
 
   """
   Boolean flag for whether the currently logged in user is subscribed to this epic
   """
   subscribed: Boolean!
+
+  """
+  Title of the epic
+  """
   title: String
+
+  """
+  Timestamp of the epic's last activity
+  """
   updatedAt: Time
 
   """

doc/api/graphql/reference/gitlab_schema.json

@@ -3342,7 +3342,7 @@
           "fields": [
             {
               "name": "author",
-              "description": null,
+              "description": "Author of the epic",
               "args": [
 
               ],
@@ -3360,7 +3360,7 @@
             },
             {
               "name": "children",
-              "description": null,
+              "description": "Children (sub-epics) of the epic",
               "args": [
                 {
                   "name": "iid",
@@ -3519,7 +3519,7 @@
             },
             {
               "name": "closedAt",
-              "description": null,
+              "description": "Timestamp of the epic's closure",
               "args": [
 
               ],
@@ -3533,7 +3533,7 @@
             },
             {
               "name": "createdAt",
-              "description": null,
+              "description": "Timestamp of the epic's creation",
               "args": [
 
               ],
@@ -3561,7 +3561,7 @@
             },
             {
               "name": "description",
-              "description": null,
+              "description": "Description of the epic",
               "args": [
 
               ],
@@ -3650,7 +3650,7 @@
             },
             {
               "name": "dueDate",
-              "description": null,
+              "description": "Due date of the epic",
               "args": [
 
               ],
@@ -3664,7 +3664,7 @@
             },
             {
               "name": "dueDateFixed",
-              "description": null,
+              "description": "Fixed due date of the epic",
               "args": [
 
               ],
@@ -3678,7 +3678,7 @@
             },
             {
               "name": "dueDateFromMilestones",
-              "description": null,
+              "description": "Inherited due date of the epic from milestones",
               "args": [
 
               ],
@@ -3692,7 +3692,7 @@
             },
             {
               "name": "dueDateIsFixed",
-              "description": null,
+              "description": "Indicates if the due date has been manually set",
               "args": [
 
               ],
@@ -3706,7 +3706,7 @@
             },
             {
               "name": "group",
-              "description": null,
+              "description": "Group to which the epic belongs",
               "args": [
 
               ],
@@ -3724,7 +3724,7 @@
             },
             {
               "name": "hasChildren",
-              "description": null,
+              "description": "Indicates if the epic has children",
               "args": [
 
               ],
@@ -3742,7 +3742,7 @@
             },
             {
               "name": "hasIssues",
-              "description": null,
+              "description": "Indicates if the epic has direct issues",
               "args": [
 
               ],
@@ -3760,7 +3760,7 @@
             },
             {
               "name": "id",
-              "description": null,
+              "description": "ID of the epic",
               "args": [
 
               ],
@@ -3778,7 +3778,7 @@
             },
             {
               "name": "iid",
-              "description": null,
+              "description": "Internal ID of the epic",
               "args": [
 
               ],
@@ -3959,7 +3959,7 @@
             },
             {
               "name": "parent",
-              "description": null,
+              "description": "Parent epic of the epic",
               "args": [
 
               ],
@@ -4067,7 +4067,7 @@
             },
             {
               "name": "relativePosition",
-              "description": "The relative position of the epic in the Epic tree",
+              "description": "The relative position of the epic in the epic tree",
               "args": [
 
               ],
@@ -4081,7 +4081,7 @@
             },
             {
               "name": "startDate",
-              "description": null,
+              "description": "Start date of the epic",
               "args": [
 
               ],
@@ -4095,7 +4095,7 @@
             },
             {
               "name": "startDateFixed",
-              "description": null,
+              "description": "Fixed start date of the epic",
               "args": [
 
               ],
@@ -4109,7 +4109,7 @@
             },
             {
               "name": "startDateFromMilestones",
-              "description": null,
+              "description": "Inherited start date of the epic from milestones",
               "args": [
 
               ],
@@ -4123,7 +4123,7 @@
             },
             {
               "name": "startDateIsFixed",
-              "description": null,
+              "description": "Indicates if the start date has been manually set",
               "args": [
 
               ],
@@ -4137,7 +4137,7 @@
             },
             {
               "name": "state",
-              "description": null,
+              "description": "State of the epic",
               "args": [
 
               ],
@@ -4173,7 +4173,7 @@
             },
             {
               "name": "title",
-              "description": null,
+              "description": "Title of the epic",
               "args": [
 
               ],
@@ -4187,7 +4187,7 @@
             },
             {
               "name": "updatedAt",
-              "description": null,
+              "description": "Timestamp of the epic's last activity",
               "args": [
 
               ],

doc/api/graphql/reference/index.md

@@ -195,32 +195,32 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
 | `userPermissions` | EpicPermissions! | Permissions for the current user on the resource |
-| `id` | ID! |  |
-| `iid` | ID! |  |
-| `title` | String |  |
-| `description` | String |  |
-| `state` | EpicState! |  |
-| `group` | Group! |  |
-| `parent` | Epic |  |
-| `author` | User! |  |
-| `startDate` | Time |  |
-| `startDateIsFixed` | Boolean |  |
-| `startDateFixed` | Time |  |
-| `startDateFromMilestones` | Time |  |
-| `dueDate` | Time |  |
-| `dueDateIsFixed` | Boolean |  |
-| `dueDateFixed` | Time |  |
-| `dueDateFromMilestones` | Time |  |
+| `id` | ID! | ID of the epic |
+| `iid` | ID! | Internal ID of the epic |
+| `title` | String | Title of the epic |
+| `description` | String | Description of the epic |
+| `state` | EpicState! | State of the epic |
+| `group` | Group! | Group to which the epic belongs |
+| `parent` | Epic | Parent epic of the epic |
+| `author` | User! | Author of the epic |
+| `startDate` | Time | Start date of the epic |
+| `startDateIsFixed` | Boolean | Indicates if the start date has been manually set |
+| `startDateFixed` | Time | Fixed start date of the epic |
+| `startDateFromMilestones` | Time | Inherited start date of the epic from milestones |
+| `dueDate` | Time | Due date of the epic |
+| `dueDateIsFixed` | Boolean | Indicates if the due date has been manually set |
+| `dueDateFixed` | Time | Fixed due date of the epic |
+| `dueDateFromMilestones` | Time | Inherited due date of the epic from milestones |
 | `upvotes` | Int! | Number of upvotes the epic has received |
 | `downvotes` | Int! | Number of downvotes the epic has received |
-| `closedAt` | Time |  |
-| `createdAt` | Time |  |
-| `updatedAt` | Time |  |
-| `hasChildren` | Boolean! |  |
-| `hasIssues` | Boolean! |  |
+| `closedAt` | Time | Timestamp of the epic's closure |
+| `createdAt` | Time | Timestamp of the epic's creation |
+| `updatedAt` | Time | Timestamp of the epic's last activity |
+| `hasChildren` | Boolean! | Indicates if the epic has children |
+| `hasIssues` | Boolean! | Indicates if the epic has direct issues |
 | `webPath` | String! |  |
 | `webUrl` | String! |  |
-| `relativePosition` | Int | The relative position of the epic in the Epic tree |
+| `relativePosition` | Int | The relative position of the epic in the epic tree |
 | `relationPath` | String |  |
 | `reference` | String! |  |
 | `subscribed` | Boolean! | Boolean flag for whether the currently logged in user is subscribed to this epic |

ee/app/graphql/types/epic_type.rb

@@ -12,57 +12,87 @@ module Types
 
     implements(Types::Notes::NoteableType)
 
-    field :id, GraphQL::ID_TYPE, null: false # rubocop:disable Graphql/Descriptions
-    field :iid, GraphQL::ID_TYPE, null: false # rubocop:disable Graphql/Descriptions
-    field :title, GraphQL::STRING_TYPE, null: true # rubocop:disable Graphql/Descriptions
-    field :description, GraphQL::STRING_TYPE, null: true # rubocop:disable Graphql/Descriptions
-    field :state, EpicStateEnum, null: false # rubocop:disable Graphql/Descriptions
-
-    field :group, GroupType, # rubocop:disable Graphql/Descriptions
-          null: false,
+    field :id, GraphQL::ID_TYPE, null: false,
+          description: 'ID of the epic'
+    field :iid, GraphQL::ID_TYPE, null: false,
+          description: 'Internal ID of the epic'
+    field :title, GraphQL::STRING_TYPE, null: true,
+          description: 'Title of the epic'
+    field :description, GraphQL::STRING_TYPE, null: true,
+          description: 'Description of the epic'
+    field :state, EpicStateEnum, null: false,
+          description: 'State of the epic'
+
+    field :group, GroupType, null: false,
+          description: 'Group to which the epic belongs',
           resolve: -> (obj, _args, _ctx) { Gitlab::Graphql::Loaders::BatchModelLoader.new(Group, obj.group_id).find }
-    field :parent, EpicType, # rubocop:disable Graphql/Descriptions
-          null: true,
+    field :parent, EpicType, null: true,
+          description: 'Parent epic of the epic',
           resolve: -> (obj, _args, _ctx) { Gitlab::Graphql::Loaders::BatchModelLoader.new(Epic, obj.parent_id).find }
-    field :author, Types::UserType, # rubocop:disable Graphql/Descriptions
-          null: false,
+    field :author, Types::UserType, null: false,
+          description: 'Author of the epic',
           resolve: -> (obj, _args, _ctx) { Gitlab::Graphql::Loaders::BatchModelLoader.new(User, obj.author_id).find }
 
-    field :start_date, Types::TimeType, null: true # rubocop:disable Graphql/Descriptions
-    field :start_date_is_fixed, GraphQL::BOOLEAN_TYPE, null: true, method: :start_date_is_fixed?, authorize: :admin_epic # rubocop:disable Graphql/Descriptions
-    field :start_date_fixed, Types::TimeType, null: true, authorize: :admin_epic # rubocop:disable Graphql/Descriptions
-    field :start_date_from_milestones, Types::TimeType, null: true, authorize: :admin_epic # rubocop:disable Graphql/Descriptions
-
-    field :due_date, Types::TimeType, null: true # rubocop:disable Graphql/Descriptions
-    field :due_date_is_fixed, GraphQL::BOOLEAN_TYPE, null: true, method: :due_date_is_fixed?, authorize: :admin_epic # rubocop:disable Graphql/Descriptions
-    field :due_date_fixed, Types::TimeType, null: true, authorize: :admin_epic # rubocop:disable Graphql/Descriptions
-    field :due_date_from_milestones, Types::TimeType, null: true, authorize: :admin_epic # rubocop:disable Graphql/Descriptions
-
-    field :upvotes, GraphQL::INT_TYPE, null: false, description: 'Number of upvotes the epic has received'
-    field :downvotes, GraphQL::INT_TYPE, null: false, description: 'Number of downvotes the epic has received'
-
-    field :closed_at, Types::TimeType, null: true # rubocop:disable Graphql/Descriptions
-    field :created_at, Types::TimeType, null: true # rubocop:disable Graphql/Descriptions
-    field :updated_at, Types::TimeType, null: true # rubocop:disable Graphql/Descriptions
-
-    field :children, # rubocop:disable Graphql/Descriptions
-          ::Types::EpicType.connection_type,
-          null: true,
+    field :start_date, Types::TimeType, null: true,
+          description: 'Start date of the epic'
+    field :start_date_is_fixed, GraphQL::BOOLEAN_TYPE, null: true,
+          description: 'Indicates if the start date has been manually set',
+          method: :start_date_is_fixed?, authorize: :admin_epic
+    field :start_date_fixed, Types::TimeType, null: true,
+          description: 'Fixed start date of the epic',
+          authorize: :admin_epic
+    field :start_date_from_milestones, Types::TimeType, null: true,
+          description: 'Inherited start date of the epic from milestones',
+          authorize: :admin_epic
+
+    field :due_date, Types::TimeType, null: true,
+          description: 'Due date of the epic'
+    field :due_date_is_fixed, GraphQL::BOOLEAN_TYPE, null: true,
+          description: 'Indicates if the due date has been manually set',
+          method: :due_date_is_fixed?, authorize: :admin_epic
+    field :due_date_fixed, Types::TimeType, null: true,
+          description: 'Fixed due date of the epic',
+          authorize: :admin_epic
+    field :due_date_from_milestones, Types::TimeType, null: true,
+          description: 'Inherited due date of the epic from milestones',
+          authorize: :admin_epic
+
+    field :upvotes, GraphQL::INT_TYPE, null: false,
+          description: 'Number of upvotes the epic has received'
+    field :downvotes, GraphQL::INT_TYPE, null: false,
+          description: 'Number of downvotes the epic has received'
+
+    field :closed_at, Types::TimeType, null: true,
+          description: "Timestamp of the epic's closure"
+    field :created_at, Types::TimeType, null: true,
+          description: "Timestamp of the epic's creation"
+    field :updated_at, Types::TimeType, null: true,
+          description: "Timestamp of the epic's last activity"
+
+    field :children, ::Types::EpicType.connection_type, null: true,
+          description: 'Children (sub-epics) of the epic',
           resolver: ::Resolvers::EpicResolver
     field :labels, Types::LabelType.connection_type, null: true,
           description: 'Labels assigned to the epic'
 
-    field :has_children, GraphQL::BOOLEAN_TYPE, null: false, method: :has_children? # rubocop:disable Graphql/Descriptions
-    field :has_issues, GraphQL::BOOLEAN_TYPE, null: false, method: :has_issues? # rubocop:disable Graphql/Descriptions
+    field :has_children, GraphQL::BOOLEAN_TYPE, null: false,
+          description: 'Indicates if the epic has children',
+          method: :has_children?
+    field :has_issues, GraphQL::BOOLEAN_TYPE, null: false,
+          description: 'Indicates if the epic has direct issues',
+          method: :has_issues?
 
     field :web_path, GraphQL::STRING_TYPE, null: false, method: :group_epic_path # rubocop:disable Graphql/Descriptions
     field :web_url, GraphQL::STRING_TYPE, null: false, method: :group_epic_url # rubocop:disable Graphql/Descriptions
-    field :relative_position, GraphQL::INT_TYPE, null: true, description: 'The relative position of the epic in the Epic tree'
+    field :relative_position, GraphQL::INT_TYPE, null: true,
+          description: 'The relative position of the epic in the epic tree'
     field :relation_path, GraphQL::STRING_TYPE, null: true, method: :group_epic_link_path # rubocop:disable Graphql/Descriptions
     field :reference, GraphQL::STRING_TYPE, null: false, method: :epic_reference do # rubocop:disable Graphql/Descriptions
       argument :full, GraphQL::BOOLEAN_TYPE, required: false, default_value: false # rubocop:disable Graphql/Descriptions
     end
-    field :participants, Types::UserType.connection_type, null: true, complexity: 5, description: 'List of participants for the epic'
+    field :participants, Types::UserType.connection_type, null: true,
+          description: 'List of participants for the epic',
+          complexity: 5
 
     field :subscribed, GraphQL::BOOLEAN_TYPE,
       method: :subscribed?,