Add latest changes from gitlab-org/gitlab@master

2 files changed, 89 insertions, 29 deletions

diff --git a/lib/gitlab/graphql/docs/helper.rb b/lib/gitlab/graphql/docs/helper.rb
index 68a2a78d0d4..e9ff85d9ca9 100644
--- a/lib/gitlab/graphql/docs/helper.rb
+++ b/lib/gitlab/graphql/docs/helper.rb
@@ -27,16 +27,18 @@ module Gitlab
           MD
         end
 
-        def render_name_and_description(object)
-          content = "### `#{object[:name]}`\n"
+        def render_name_and_description(object, level = 3)
+          content = []
+
+          content << "#{'#' * level} `#{object[:name]}`"
 
           if object[:description].present?
-            content += "\n#{object[:description]}"
-            content += '.' unless object[:description].ends_with?('.')
-            content += "\n"
+            desc = object[:description].strip
+            desc += '.' unless desc.ends_with?('.')
+            content << desc
           end
 
-          content
+          content.join("\n\n")
         end
 
         def sorted_by_name(objects)
@@ -46,18 +48,15 @@ module Gitlab
         end
 
         def render_field(field)
-          '| %s | %s | %s |' % [
-            render_name(field),
-            render_field_type(field[:type][:info]),
-            render_description(field)
-            ]
+          row(render_name(field), render_field_type(field[:type]), render_description(field))
         end
 
         def render_enum_value(value)
-          '| %s | %s |' % [
-            render_name(value),
-            render_description(value)
-            ]
+          row(render_name(value), render_description(value))
+        end
+
+        def row(*values)
+          "| #{values.join(' | ')} |"
         end
 
         def render_name(object)
@@ -74,27 +73,19 @@ module Gitlab
           "**Deprecated:** #{object[:deprecation_reason]}"
         end
 
-        # Some fields types are arrays of other types and are displayed
-        # on docs wrapped in square brackets, for example: [String!].
-        # This makes GitLab docs renderer thinks they are links so here
-        # we change them to be rendered as: String! => Array.
         def render_field_type(type)
-          array_type = type[/\[(.+)\]/, 1]
+          "[`#{type[:info]}`](##{type[:name].downcase})"
+        end
 
-          if array_type
-            "#{array_type} => Array"
-          else
-            type
-          end
+        def render_return_type(query)
+          "Returns #{render_field_type(query[:type])}.\n"
         end
 
         # We are ignoring connections and built in types for now,
         # they should be added when queries are generated.
         def objects
           object_types = graphql_object_types.select do |object_type|
-            !object_type[:name]["Connection"] &&
-              !object_type[:name]["Edge"] &&
-              !object_type[:name]["__"]
+            !object_type[:name]["__"]
           end
 
           object_types.each do |type|
@@ -109,7 +100,7 @@ module Gitlab
         # We ignore the built-in enum types.
         def enums
           graphql_enum_types.select do |enum_type|
-            !enum_type[:name].in?(%w(__DirectiveLocation __TypeKind))
+            !enum_type[:name].in?(%w[__DirectiveLocation __TypeKind])
           end
         end
       end
diff --git a/lib/gitlab/graphql/docs/templates/default.md.haml b/lib/gitlab/graphql/docs/templates/default.md.haml
index 5ae83fd51c5..847f1777b08 100644
--- a/lib/gitlab/graphql/docs/templates/default.md.haml
+++ b/lib/gitlab/graphql/docs/templates/default.md.haml
@@ -28,6 +28,8 @@
 
 - sorted_by_name(queries).each do |query|
   = render_name_and_description(query)
+  \
+  = render_return_type(query)
   - unless query[:arguments].empty?
     ~ "#### Arguments\n"
     ~ "| Name | Type | Description |"
@@ -52,6 +54,7 @@
 - objects.each do |type|
   - unless type[:fields].empty?
     = render_name_and_description(type)
+    \
     ~ "| Field | Type | Description |"
     ~ "| ----- | ---- | ----------- |"
     - sorted_by_name(type[:fields]).each do |field|
@@ -72,8 +75,74 @@
 - enums.each do |enum|
   - unless enum[:values].empty?
     = render_name_and_description(enum)
+    \
     ~ "| Value | Description |"
     ~ "| ----- | ----------- |"
     - sorted_by_name(enum[:values]).each do |value|
       = render_enum_value(value)
     \
+
+:plain
+  ## Scalar types
+
+  Scalar values are atomic values, and do not have fields of their own.
+  Basic scalars include strings, boolean values, and numbers. This schema also
+  defines various custom scalar values, such as types for times and dates.
+
+  This schema includes custom scalar types for identifiers, with a specific type for
+  each kind of object.
+
+  For more information, read about [Scalar Types](https://graphql.org/learn/schema/#scalar-types) on `graphql.org`.
+\
+
+- graphql_scalar_types.each do |type|
+  = render_name_and_description(type)
+  \
+
+:plain
+  ## Abstract types
+
+  Abstract types (unions and interfaces) are ways the schema can represent
+  values that may be one of several concrete types.
+
+  - A [`Union`](https://graphql.org/learn/schema/#union-types) is a set of possible types.
+    The types might not have any fields in common.
+  - An [`Interface`](https://graphql.org/learn/schema/#interfaces) is a defined set of fields.
+    Types may `implement` an interface, which
+    guarantees that they have all the fields in the set. A type may implement more than
+    one interface.
+
+  See the [GraphQL documentation](https://graphql.org/learn/) for more information on using
+  abstract types.
+\
+
+:plain
+  ### Unions
+\
+
+- graphql_union_types.each do |type|
+  = render_name_and_description(type, 4)
+  \
+  One of:
+  \
+  - type[:possible_types].each do |type_name|
+    ~ "- [`#{type_name}`](##{type_name.downcase})"
+  \
+
+:plain
+  ### Interfaces
+\
+
+- graphql_interface_types.each do |type|
+  = render_name_and_description(type, 4)
+  \
+  Implementations:
+  \
+  - type[:implemented_by].each do |type_name|
+    ~ "- [`#{type_name}`](##{type_name.downcase})"
+  \
+  ~ "| Field | Type | Description |"
+  ~ "| ----- | ---- | ----------- |"
+  - sorted_by_name(type[:fields] + type[:connections]).each do |field|
+    = render_field(field)
+  \