Backfill GraphQL field descriptions

- Some use API docs copy-pasted material (a smell)
- Some are really obvious (e.g. "user's name"
- Some use labels from the UI

app/graphql/types/commit_type.rb

@@ -8,23 +8,31 @@ module Types
 
     present_using CommitPresenter
 
-    field :id, type: GraphQL::ID_TYPE, null: false # rubocop:disable Graphql/Descriptions
-    field :sha, type: GraphQL::STRING_TYPE, null: false # rubocop:disable Graphql/Descriptions
-    field :title, type: GraphQL::STRING_TYPE, null: true # rubocop:disable Graphql/Descriptions
-    field :description, type: GraphQL::STRING_TYPE, null: true # rubocop:disable Graphql/Descriptions
-    field :message, type: GraphQL::STRING_TYPE, null: true # rubocop:disable Graphql/Descriptions
-    field :authored_date, type: Types::TimeType, null: true # rubocop:disable Graphql/Descriptions
-    field :web_url, type: GraphQL::STRING_TYPE, null: false # rubocop:disable Graphql/Descriptions
-    field :signature_html, type: GraphQL::STRING_TYPE,
-      null: true, calls_gitaly: true, description: 'Rendered html for the commit signature'
+    field :id, type: GraphQL::ID_TYPE, null: false,
+          description: 'ID (global ID) of the commit'
+    field :sha, type: GraphQL::STRING_TYPE, null: false,
+          description: 'SHA1 ID of the commit'
+    field :title, type: GraphQL::STRING_TYPE, null: true,
+          description: 'Title of the commit message'
+    field :description, type: GraphQL::STRING_TYPE, null: true,
+          description: 'Description of the commit message'
+    field :message, type: GraphQL::STRING_TYPE, null: true,
+          description: 'Raw commit message'
+    field :authored_date, type: Types::TimeType, null: true,
+          description: 'Timestamp of when the commit was authored'
+    field :web_url, type: GraphQL::STRING_TYPE, null: false,
+          description: 'Web URL of the commit'
+    field :signature_html, type: GraphQL::STRING_TYPE, null: true, calls_gitaly: true,
+          description: 'Rendered HTML of the commit signature'
 
     # models/commit lazy loads the author by email
-    field :author, type: Types::UserType, null: true # rubocop:disable Graphql/Descriptions
+    field :author, type: Types::UserType, null: true,
+          description: 'Author of the commit'
 
     field :latest_pipeline,
           type: Types::Ci::PipelineType,
           null: true,
-          description: "Latest pipeline for this commit",
+          description: "Latest pipeline of the commit",
           resolve: -> (obj, ctx, args) do
             Gitlab::Graphql::Loaders::PipelineForShaLoader.new(obj.project, obj.sha).find_last
           end

app/graphql/types/group_type.rb

@@ -8,14 +8,17 @@ module Types
 
     expose_permissions Types::PermissionTypes::Group
 
-    field :web_url, GraphQL::STRING_TYPE, null: false # rubocop:disable Graphql/Descriptions
+    field :web_url, GraphQL::STRING_TYPE, null: false,
+          description: 'Web URL of the group'
 
-    field :avatar_url, GraphQL::STRING_TYPE, null: true, resolve: -> (group, args, ctx) do # rubocop:disable Graphql/Descriptions
-      group.avatar_url(only_path: false)
-    end
+    field :avatar_url, GraphQL::STRING_TYPE, null: true,
+          description: 'Avatar URL of the group',
+          resolve: -> (group, args, ctx) do
+            group.avatar_url(only_path: false)
+          end
 
-    field :parent, GroupType, # rubocop:disable Graphql/Descriptions
-          null: true,
+    field :parent, GroupType, null: true,
+          description: 'Parent group',
           resolve: -> (obj, _args, _ctx) { Gitlab::Graphql::Loaders::BatchModelLoader.new(Group, obj.parent_id).find }
   end
 end

app/graphql/types/issue_type.rb

@@ -12,53 +12,77 @@ module Types
 
     present_using IssuePresenter
 
-    field :iid, GraphQL::ID_TYPE, null: false # rubocop:disable Graphql/Descriptions
-    field :title, GraphQL::STRING_TYPE, null: false # rubocop:disable Graphql/Descriptions
+    field :iid, GraphQL::ID_TYPE, null: false,
+          description: "Internal ID of the issue"
+    field :title, GraphQL::STRING_TYPE, null: false,
+          description: 'Title of the issue'
     markdown_field :title_html, null: true
-    field :description, GraphQL::STRING_TYPE, null: true # rubocop:disable Graphql/Descriptions
+    field :description, GraphQL::STRING_TYPE, null: true,
+          description: 'Description of the issue'
     markdown_field :description_html, null: true
-    field :state, IssueStateEnum, null: false # rubocop:disable Graphql/Descriptions
-
-    field :reference, GraphQL::STRING_TYPE, null: false, method: :to_reference do # rubocop:disable Graphql/Descriptions
-      argument :full, GraphQL::BOOLEAN_TYPE, required: false, default_value: false # rubocop:disable Graphql/Descriptions
+    field :state, IssueStateEnum, null: false,
+          description: 'State of the issue'
+
+    field :reference, GraphQL::STRING_TYPE, null: false,
+          description: 'Internal reference of the issue. Returned in shortened format by default',
+          method: :to_reference do
+      argument :full, GraphQL::BOOLEAN_TYPE, required: false, default_value: false,
+               description: 'Boolean option specifying whether the reference should be returned in full'
     end
 
-    field :author, Types::UserType, # rubocop:disable Graphql/Descriptions
-          null: false,
+    field :author, Types::UserType, null: false,
+          description: 'User that created the issue',
           resolve: -> (obj, _args, _ctx) { Gitlab::Graphql::Loaders::BatchModelLoader.new(User, obj.author_id).find }
 
     # Remove complexity when BatchLoader is used
-    field :assignees, Types::UserType.connection_type, null: true, complexity: 5 # rubocop:disable Graphql/Descriptions
+    field :assignees, Types::UserType.connection_type, null: true, complexity: 5,
+          description: 'Assignees of the issue'
 
     # Remove complexity when BatchLoader is used
-    field :labels, Types::LabelType.connection_type, null: true, complexity: 5 # rubocop:disable Graphql/Descriptions
-    field :milestone, Types::MilestoneType, # rubocop:disable Graphql/Descriptions
-          null: true,
+    field :labels, Types::LabelType.connection_type, null: true, complexity: 5,
+          description: 'Labels of the issue'
+    field :milestone, Types::MilestoneType, null: true,
+          description: 'Milestone of the issue',
           resolve: -> (obj, _args, _ctx) { Gitlab::Graphql::Loaders::BatchModelLoader.new(Milestone, obj.milestone_id).find }
 
-    field :due_date, Types::TimeType, null: true # rubocop:disable Graphql/Descriptions
-    field :confidential, GraphQL::BOOLEAN_TYPE, null: false # rubocop:disable Graphql/Descriptions
-    field :discussion_locked, GraphQL::BOOLEAN_TYPE, # rubocop:disable Graphql/Descriptions
-          null: false,
+    field :due_date, Types::TimeType, null: true,
+          description: 'Due date of the issue'
+    field :confidential, GraphQL::BOOLEAN_TYPE, null: false,
+          description: 'Indicates the issue is confidential'
+    field :discussion_locked, GraphQL::BOOLEAN_TYPE, null: false,
+          description: 'Indicates discussion is locked on the issue',
           resolve: -> (obj, _args, _ctx) { !!obj.discussion_locked }
 
-    field :upvotes, GraphQL::INT_TYPE, null: false # rubocop:disable Graphql/Descriptions
-    field :downvotes, GraphQL::INT_TYPE, null: false # rubocop:disable Graphql/Descriptions
-    field :user_notes_count, GraphQL::INT_TYPE, null: false # rubocop:disable Graphql/Descriptions
-    field :web_path, GraphQL::STRING_TYPE, null: false, method: :issue_path # rubocop:disable Graphql/Descriptions
-    field :web_url, GraphQL::STRING_TYPE, null: false # rubocop:disable Graphql/Descriptions
-    field :relative_position, GraphQL::INT_TYPE, null: true # rubocop:disable Graphql/Descriptions
-
-    field :participants, Types::UserType.connection_type, null: true, complexity: 5, description: 'List of participants for the issue'
-    field :time_estimate, GraphQL::INT_TYPE, null: false, description: 'The time estimate on the issue'
-    field :total_time_spent, GraphQL::INT_TYPE, null: false, description: 'Total time reported as spent on the issue'
-
-    field :closed_at, Types::TimeType, null: true # rubocop:disable Graphql/Descriptions
-
-    field :created_at, Types::TimeType, null: false # rubocop:disable Graphql/Descriptions
-    field :updated_at, Types::TimeType, null: false # rubocop:disable Graphql/Descriptions
-
-    field :task_completion_status, Types::TaskCompletionStatus, null: false # rubocop:disable Graphql/Descriptions
+    field :upvotes, GraphQL::INT_TYPE, null: false,
+          description: 'Number of upvotes the issue has received'
+    field :downvotes, GraphQL::INT_TYPE, null: false,
+          description: 'Number of downvotes the issue has received'
+    field :user_notes_count, GraphQL::INT_TYPE, null: false,
+          description: 'Number of user notes of the issue'
+    field :web_path, GraphQL::STRING_TYPE, null: false, method: :issue_path,
+          description: 'Web path of the issue'
+    field :web_url, GraphQL::STRING_TYPE, null: false,
+          description: 'Web URL of the issue'
+    field :relative_position, GraphQL::INT_TYPE, null: true,
+          description: 'Relative position of the issue (used for positioning in epic tree and issue boards)'
+
+    field :participants, Types::UserType.connection_type, null: true, complexity: 5,
+          description: 'List of participants in the issue'
+    field :time_estimate, GraphQL::INT_TYPE, null: false,
+          description: 'Time estimate of the issue'
+    field :total_time_spent, GraphQL::INT_TYPE, null: false,
+          description: 'Total time reported as spent on the issue'
+
+    field :closed_at, Types::TimeType, null: true,
+          description: 'Timestamp of when the issue was closed'
+
+    field :created_at, Types::TimeType, null: false,
+          description: 'Timestamp of when the issue was created'
+    field :updated_at, Types::TimeType, null: false,
+          description: 'Timestamp of when the issue was last updated'
+
+    field :task_completion_status, Types::TaskCompletionStatus, null: false,
+          description: 'Task completion status of the issue'
   end
 end
 

app/graphql/types/label_type.rb

@@ -6,10 +6,14 @@ module Types
 
     authorize :read_label
 
-    field :description, GraphQL::STRING_TYPE, null: true # rubocop:disable Graphql/Descriptions
+    field :description, GraphQL::STRING_TYPE, null: true,
+          description: 'Description of the label (markdown rendered as HTML for caching)'
     markdown_field :description_html, null: true
-    field :title, GraphQL::STRING_TYPE, null: false # rubocop:disable Graphql/Descriptions
-    field :color, GraphQL::STRING_TYPE, null: false # rubocop:disable Graphql/Descriptions
-    field :text_color, GraphQL::STRING_TYPE, null: false # rubocop:disable Graphql/Descriptions
+    field :title, GraphQL::STRING_TYPE, null: false,
+          description: 'Content of the label'
+    field :color, GraphQL::STRING_TYPE, null: false,
+          description: 'Background color of the label'
+    field :text_color, GraphQL::STRING_TYPE, null: false,
+          description: 'Text color of the label'
   end
 end

app/graphql/types/metadata_type.rb

@@ -6,7 +6,9 @@ module Types
 
     authorize :read_instance_metadata
 
-    field :version, GraphQL::STRING_TYPE, null: false # rubocop:disable Graphql/Descriptions
-    field :revision, GraphQL::STRING_TYPE, null: false # rubocop:disable Graphql/Descriptions
+    field :version, GraphQL::STRING_TYPE, null: false,
+          description: 'Version'
+    field :revision, GraphQL::STRING_TYPE, null: false,
+          description: 'Revision'
   end
 end

app/graphql/types/milestone_type.rb

@@ -6,14 +6,21 @@ module Types
 
     authorize :read_milestone
 
-    field :description, GraphQL::STRING_TYPE, null: true # rubocop:disable Graphql/Descriptions
-    field :title, GraphQL::STRING_TYPE, null: false # rubocop:disable Graphql/Descriptions
-    field :state, GraphQL::STRING_TYPE, null: false # rubocop:disable Graphql/Descriptions
+    field :description, GraphQL::STRING_TYPE, null: true,
+          description: 'Description of the milestone'
+    field :title, GraphQL::STRING_TYPE, null: false,
+          description: 'Title of the milestone'
+    field :state, GraphQL::STRING_TYPE, null: false,
+          description: 'State of the milestone'
 
-    field :due_date, Types::TimeType, null: true # rubocop:disable Graphql/Descriptions
-    field :start_date, Types::TimeType, null: true # rubocop:disable Graphql/Descriptions
+    field :due_date, Types::TimeType, null: true,
+          description: 'Timestamp of the milestone due date'
+    field :start_date, Types::TimeType, null: true,
+          description: 'Timestamp of the milestone start date'
 
-    field :created_at, Types::TimeType, null: false # rubocop:disable Graphql/Descriptions
-    field :updated_at, Types::TimeType, null: false # rubocop:disable Graphql/Descriptions
+    field :created_at, Types::TimeType, null: false,
+          description: 'Timestamp of milestone creation'
+    field :updated_at, Types::TimeType, null: false,
+          description: 'Timestamp of last milestone update'
   end
 end

app/graphql/types/namespace_type.rb

@@ -6,27 +6,35 @@ module Types
 
     authorize :read_namespace
 
-    field :id, GraphQL::ID_TYPE, null: false # rubocop:disable Graphql/Descriptions
+    field :id, GraphQL::ID_TYPE, null: false,
+          description: 'ID of the namespace'
 
-    field :name, GraphQL::STRING_TYPE, null: false # rubocop:disable Graphql/Descriptions
-    field :path, GraphQL::STRING_TYPE, null: false # rubocop:disable Graphql/Descriptions
-    field :full_name, GraphQL::STRING_TYPE, null: false # rubocop:disable Graphql/Descriptions
-    field :full_path, GraphQL::ID_TYPE, null: false # rubocop:disable Graphql/Descriptions
+    field :name, GraphQL::STRING_TYPE, null: false,
+          description: 'Name of the namespace'
+    field :path, GraphQL::STRING_TYPE, null: false,
+          description: 'Path of the namespace'
+    field :full_name, GraphQL::STRING_TYPE, null: false,
+          description: 'Full name of the namespace'
+    field :full_path, GraphQL::ID_TYPE, null: false,
+          description: 'Full path of the namespace'
 
-    field :description, GraphQL::STRING_TYPE, null: true # rubocop:disable Graphql/Descriptions
+    field :description, GraphQL::STRING_TYPE, null: true,
+          description: 'Description of the namespace'
     markdown_field :description_html, null: true
-    field :visibility, GraphQL::STRING_TYPE, null: true # rubocop:disable Graphql/Descriptions
-    field :lfs_enabled, GraphQL::BOOLEAN_TYPE, null: true, method: :lfs_enabled? # rubocop:disable Graphql/Descriptions
-    field :request_access_enabled, GraphQL::BOOLEAN_TYPE, null: true # rubocop:disable Graphql/Descriptions
+    field :visibility, GraphQL::STRING_TYPE, null: true,
+          description: 'Visibility of the namespace'
+    field :lfs_enabled, GraphQL::BOOLEAN_TYPE, null: true, method: :lfs_enabled?,
+          description: 'Indicates if Large File Storage (LFS) is enabled for namespace'
+    field :request_access_enabled, GraphQL::BOOLEAN_TYPE, null: true,
+          description: 'Indicates if users can request access to namespace'
 
     field :root_storage_statistics, Types::RootStorageStatisticsType,
           null: true,
-          description: 'The aggregated storage statistics. Only available for root namespaces',
+          description: 'Aggregated storage statistics of the namespace. Only available for root namespaces',
           resolve: -> (obj, _args, _ctx) { Gitlab::Graphql::Loaders::BatchRootStorageStatisticsLoader.new(obj.id).find }
 
-    field :projects, # rubocop:disable Graphql/Descriptions
-          Types::ProjectType.connection_type,
-          null: false,
+    field :projects, Types::ProjectType.connection_type, null: false,
+          description: 'Projects within this namespace',
           resolver: ::Resolvers::NamespaceProjectsResolver
   end
 end

app/graphql/types/project_statistics_type.rb

@@ -6,13 +6,20 @@ module Types
 
     authorize :read_statistics
 
-    field :commit_count, GraphQL::INT_TYPE, null: false # rubocop:disable Graphql/Descriptions
+    field :commit_count, GraphQL::INT_TYPE, null: false,
+          description: 'Commit count of the project'
 
-    field :storage_size, GraphQL::INT_TYPE, null: false # rubocop:disable Graphql/Descriptions
-    field :repository_size, GraphQL::INT_TYPE, null: false # rubocop:disable Graphql/Descriptions
-    field :lfs_objects_size, GraphQL::INT_TYPE, null: false # rubocop:disable Graphql/Descriptions
-    field :build_artifacts_size, GraphQL::INT_TYPE, null: false # rubocop:disable Graphql/Descriptions
-    field :packages_size, GraphQL::INT_TYPE, null: false # rubocop:disable Graphql/Descriptions
-    field :wiki_size, GraphQL::INT_TYPE, null: true # rubocop:disable Graphql/Descriptions
+    field :storage_size, GraphQL::INT_TYPE, null: false,
+          description: 'Storage size of the project'
+    field :repository_size, GraphQL::INT_TYPE, null: false,
+          description: 'Repository size of the project'
+    field :lfs_objects_size, GraphQL::INT_TYPE, null: false,
+          description: 'Large File Storage (LFS) object size of the project'
+    field :build_artifacts_size, GraphQL::INT_TYPE, null: false,
+          description: 'Build artifacts size of the project'
+    field :packages_size, GraphQL::INT_TYPE, null: false,
+          description: 'Packages size of the project'
+    field :wiki_size, GraphQL::INT_TYPE, null: true,
+          description: 'Wiki size of the project'
   end
 end

app/graphql/types/repository_type.rb

@@ -6,9 +6,13 @@ module Types
 
     authorize :download_code
 
-    field :root_ref, GraphQL::STRING_TYPE, null: true, calls_gitaly: true # rubocop:disable Graphql/Descriptions
-    field :empty, GraphQL::BOOLEAN_TYPE, null: false, method: :empty?, calls_gitaly: true # rubocop:disable Graphql/Descriptions
-    field :exists, GraphQL::BOOLEAN_TYPE, null: false, method: :exists? # rubocop:disable Graphql/Descriptions
-    field :tree, Types::Tree::TreeType, null: true, resolver: Resolvers::TreeResolver, calls_gitaly: true # rubocop:disable Graphql/Descriptions
+    field :root_ref, GraphQL::STRING_TYPE, null: true, calls_gitaly: true,
+          description: 'Default branch of the repository'
+    field :empty, GraphQL::BOOLEAN_TYPE, null: false, method: :empty?, calls_gitaly: true,
+          description: 'Indicates repository has no visible content'
+    field :exists, GraphQL::BOOLEAN_TYPE, null: false, method: :exists?,
+          description: 'Indicates a corresponding Git repository exists on disk'
+    field :tree, Types::Tree::TreeType, null: true, resolver: Resolvers::TreeResolver, calls_gitaly: true,
+          description: 'Tree of the repository'
   end
 end

app/graphql/types/task_completion_status.rb

@@ -8,8 +8,10 @@ module Types
     graphql_name 'TaskCompletionStatus'
     description 'Completion status of tasks'
 
-    field :count, GraphQL::INT_TYPE, null: false # rubocop:disable Graphql/Descriptions
-    field :completed_count, GraphQL::INT_TYPE, null: false # rubocop:disable Graphql/Descriptions
+    field :count, GraphQL::INT_TYPE, null: false,
+          description: 'Number of total tasks'
+    field :completed_count, GraphQL::INT_TYPE, null: false,
+          description: 'Number of completed tasks'
   end
   # rubocop: enable Graphql/AuthorizeTypes
 end

app/graphql/types/user_type.rb

@@ -8,12 +8,16 @@ module Types
 
     present_using UserPresenter
 
-    field :name, GraphQL::STRING_TYPE, null: false # rubocop:disable Graphql/Descriptions
-    field :username, GraphQL::STRING_TYPE, null: false # rubocop:disable Graphql/Descriptions
-    field :avatar_url, GraphQL::STRING_TYPE, null: false # rubocop:disable Graphql/Descriptions
-    field :web_url, GraphQL::STRING_TYPE, null: false # rubocop:disable Graphql/Descriptions
+    field :name, GraphQL::STRING_TYPE, null: false,
+          description: 'Human-readable name of the user'
+    field :username, GraphQL::STRING_TYPE, null: false,
+          description: 'Username of the user. Unique within this instance of GitLab'
+    field :avatar_url, GraphQL::STRING_TYPE, null: false,
+          description: "URL of the user's avatar"
+    field :web_url, GraphQL::STRING_TYPE, null: false,
+          description: 'Web URL of the user'
     field :todos, Types::TodoType.connection_type, null: false,
           resolver: Resolvers::TodoResolver,
-          description: 'Todos of this user'
+          description: 'Todos of the user'
   end
 end