GraphQL docs: Show descriptions for `:alpha` items

Previously the original descriptions were not displayed for "inline"
docs. This was because marking items as "alpha" leverages the our
deprecations, and for deprecated item we only display the deprecation
notice and not the original item description.

For alpha fields, we now display the warning of its instability, but do
also display the original description too.

Changelog: added

doc/api/graphql/reference/index.md

@@ -10244,7 +10244,7 @@ CI/CD variables for a project.
 | <a id="cirunnershortsha"></a>`shortSha` | [`String`](#string) | First eight characters of the runner's token used to authenticate new job requests. Used as the runner's unique ID. |
 | <a id="cirunnertaglist"></a>`tagList` | [`[String!]`](#string) | Tags associated with the runner. |
 | <a id="cirunnertokenexpiresat"></a>`tokenExpiresAt` | [`Time`](#time) | Runner token expiration time. |
-| <a id="cirunnerupgradestatus"></a>`upgradeStatus` **{warning-solid}** | [`CiRunnerUpgradeStatus`](#cirunnerupgradestatus) | **Introduced** in 14.10. This feature is in Alpha. It can be changed or removed at any time. |
+| <a id="cirunnerupgradestatus"></a>`upgradeStatus` **{warning-solid}** | [`CiRunnerUpgradeStatus`](#cirunnerupgradestatus) | **Introduced** in 14.10. This feature is in Alpha. It can be changed or removed at any time. Availability of upgrades for the runner. |
 | <a id="cirunneruserpermissions"></a>`userPermissions` | [`RunnerPermissions!`](#runnerpermissions) | Permissions for the current user on the resource. |
 | <a id="cirunnerversion"></a>`version` | [`String`](#string) | Version of the runner. |
@@ -19732,7 +19732,7 @@ Issue type.
 | <a id="issuetypeincident"></a>`INCIDENT` | Incident issue type. |
 | <a id="issuetypeissue"></a>`ISSUE` | Issue issue type. |
 | <a id="issuetyperequirement"></a>`REQUIREMENT` | Requirement issue type. |
-| <a id="issuetypetask"></a>`TASK` **{warning-solid}** | **Introduced** in 15.2. This feature is in Alpha. It can be changed or removed at any time. |
+| <a id="issuetypetask"></a>`TASK` **{warning-solid}** | **Introduced** in 15.2. This feature is in Alpha. It can be changed or removed at any time. Task issue type. Available only when feature flag `work_items` is enabled. |
 | <a id="issuetypetest_case"></a>`TEST_CASE` | Test Case issue type. |
 ### `IterationSearchableField`

lib/gitlab/graphql/deprecation.rb

@@ -94,6 +94,10 @@ def deprecation_reason
         ].compact.join(' ')
       end
 
+      def alpha?
+        reason == REASON_ALPHA
+      end
+
       private
 
       attr_reader :reason, :milestone, :replacement
@@ -127,7 +131,7 @@ def description_suffix
       # Retruns 'Introduced in <milestone>' for :alpha deprecations.
       # Formatted to markdown or plain format.
       def changed_in_milestone(format: :plain)
-        verb = if reason == REASON_ALPHA
+        verb = if alpha?
                  'Introduced'
                else
                  'Deprecated'

spec/lib/gitlab/graphql/deprecation_spec.rb

@@ -237,4 +237,20 @@
       end
     end
   end
+
+  describe '#alpha?' do
+    let(:options) { { milestone: '10.10', reason: reason } }
+
+    context 'when `reason` is `:alpha`' do
+      let(:reason) { described_class::REASON_ALPHA }
+
+      it { is_expected.to be_alpha }
+    end
+
+    context 'when `reason` is not `:alpha`' do
+      let(:reason) { described_class::REASON_RENAMED }
+
+      it { is_expected.not_to be_alpha }
+    end
+  end
 end

spec/tooling/graphql/docs/renderer_spec.rb

@@ -347,6 +347,128 @@ def resolve_type(obj, ctx)
       it_behaves_like 'renders correctly as GraphQL documentation'
     end
 
+    context 'when an argument is in alpha' do
+      let(:type) do
+        Class.new(Types::BaseObject) do
+          graphql_name 'AlphaTest'
+          description 'A thing with arguments in alpha'
+
+          field :foo,
+                type: GraphQL::Types::String,
+                null: false,
+                description: 'A description.' do
+                  argument :foo_arg, GraphQL::Types::String,
+                           required: false,
+                           description: 'Argument description.',
+                           alpha: { milestone: '101.2' }
+                end
+        end
+      end
+
+      let(:section) do
+        <<~DOC
+         ##### `AlphaTest.foo`
+
+         A description.
+
+         Returns [`String!`](#string).
+
+         ###### Arguments
+
+         | Name | Type | Description |
+         | ---- | ---- | ----------- |
+         | <a id="alphatestfoofooarg"></a>`fooArg` **{warning-solid}** | [`String`](#string) | **Introduced** in 101.2. This feature is in Alpha. It can be changed or removed at any time. Argument description. |
+        DOC
+      end
+
+      it_behaves_like 'renders correctly as GraphQL documentation'
+    end
+
+    context 'when a field is in alpha' do
+      let(:type) do
+        Class.new(Types::BaseObject) do
+          graphql_name 'AlphaTest'
+          description 'A thing with fields in alpha'
+
+          field :foo,
+                type: GraphQL::Types::String,
+                null: false,
+                alpha: { milestone: '1.10' },
+                description: 'A description.'
+          field :foo_with_args,
+                type: GraphQL::Types::String,
+                null: false,
+                alpha: { milestone: '1.10' },
+                description: 'A description.' do
+                  argument :arg, GraphQL::Types::Int, required: false, description: 'Argity'
+                end
+        end
+      end
+
+      let(:section) do
+        <<~DOC
+          ### `AlphaTest`
+
+          A thing with fields in alpha.
+
+          #### Fields
+
+          | Name | Type | Description |
+          | ---- | ---- | ----------- |
+          | <a id="alphatestfoo"></a>`foo` **{warning-solid}** | [`String!`](#string) | **Introduced** in 1.10. This feature is in Alpha. It can be changed or removed at any time. A description. |
+
+          #### Fields with arguments
+
+          ##### `AlphaTest.fooWithArgs`
+
+          A description.
+
+          WARNING:
+          **Introduced** in 1.10.
+          This feature is in Alpha. It can be changed or removed at any time.
+
+          Returns [`String!`](#string).
+
+          ###### Arguments
+
+          | Name | Type | Description |
+          | ---- | ---- | ----------- |
+          | <a id="alphatestfoowithargsarg"></a>`arg` | [`Int`](#int) | Argity. |
+        DOC
+      end
+
+      it_behaves_like 'renders correctly as GraphQL documentation'
+    end
+
+    context 'when a Query.field is in alpha' do
+      before do
+        query_type.field(
+          name: :bar,
+          type: type,
+          null: true,
+          description: 'A bar',
+          alpha: { milestone: '10.11' }
+        )
+      end
+
+      let(:type) { ::GraphQL::Types::Int }
+      let(:section) do
+        <<~DOC
+          ### `Query.bar`
+
+          A bar.
+
+          WARNING:
+          **Introduced** in 10.11.
+          This feature is in Alpha. It can be changed or removed at any time.
+
+          Returns [`Int`](#int).
+        DOC
+      end
+
+      it_behaves_like 'renders correctly as GraphQL documentation'
+    end
+
     context 'when a field has an Enumeration type' do
       let(:type) do
         enum_type = Class.new(Types::BaseEnum) do

tooling/graphql/docs/helper.rb

@@ -315,14 +315,17 @@ def doc_reference(object, owner)
         def render_deprecation(object, owner, context)
           buff = []
           deprecation = schema_deprecation(owner, object[:name])
+          original_description = deprecation&.original_description || render_description_of(object, owner)
 
-          buff << (deprecation&.original_description || render_description_of(object, owner)) if context == :block
+          buff << original_description if context == :block
           buff << if deprecation
                     deprecation.markdown(context: context)
                   else
                     "**Deprecated:** #{object[:deprecation_reason]}"
                   end
 
+          buff << original_description if context == :inline && deprecation&.alpha?
+
           join(context, buff)
         end