docs: improve UX

Author: jippi

schema/docs.tmpl

@@ -1,11 +1,13 @@
 {{- define "enum_attribute" -}}
-- `{{ .BlockName }}` ({{ if .Optional }}optional {{ end }}enum) {{ .Description }}
-  {{- range .Enum.Values }}
-      - `{{ .Name }}` - {{ .Description }}
-  {{- end -}}
-{{- end -}}
+- `#!css {{ .BlockName }}` ({{ if .Optional }}optional {{ end }}enum) {{ .Description }}
+
+      *The following values are valid:*
+
+{{ range .Enum.Values }}      - `{{ .Name }}` {{ .Description }}
+{{ end }}
+{{ end -}}
 
-{{- define "single_attribute" -}}- `{{ .BlockName }}` ({{ if .Optional }}optional {{ end }}{{ .Type }}){{ if .Description}} {{ .Description -}}{{ end }}{{- end -}}
+{{- define "single_attribute" -}}- `#!css {{ .BlockName }}` ({{ if .Optional }}optional {{ end }}{{ .Type }}){{ if .Description}} {{ .Description -}}{{ end }}{{- end -}}
 
 {{- define "description" }}{{ if .Description }}
 {{ .Description }}
@@ -21,8 +23,8 @@
 
 {{- define "attributes" -}}{{- range .Attributes -}}
 {{- if .IsCustomType }}{{ template "custom_type" . }}
-{{- else if .IsEnum }}{{- template "enum_attribute" . }}
-{{- else }}{{- template "single_attribute" . }}
+{{- else if .IsEnum }}{{ template "enum_attribute" . }}
+{{- else }}{{ template "single_attribute" . }}
 {{ end }}
 {{- end -}}
 {{- end -}}

schema/gitlab.go

@@ -323,7 +323,7 @@ func (p *Property) BlockName() string {
 }
 
 func sortSlice(i, j *Property) int {
-	// non-custom types first
+	// Custom types last
 	if i.IsCustomType && j.IsCustomType {
 		return 0
 	}
@@ -336,5 +336,6 @@ func sortSlice(i, j *Property) int {
 		return -1
 	}
 
+	// Everything else sorted by name
 	return cmp.Compare(i.Name, j.Name)
 }

schema/gitlab.schema.graphqls

@@ -132,7 +132,9 @@ type ContextProject {
   # Connections
   #
 
+  "Labels available on this project"
   Labels: [ContextLabel!] @generated
+
   ResponseLabels: ContextLabelNode @internal @graphql(key: "labels(first: 200)")
   MergeRequest: ContextMergeRequest @internal @graphql(key: "mergeRequest(iid: $mr_id)")
   ResponseGroup: ContextGroup @internal @graphql(key: "group")
@@ -247,32 +249,48 @@ type ContextMergeRequest {
 
   "Changes to a single file"
   DiffStats: [ContextDiffStat!]
+  "Labels available on this merge request"
   Labels: [ContextLabel!] @generated
-  ResponseLabels: ContextLabelNode @internal @graphql(key: "labels(first: 200)")
-  ResponseFirstCommits: ContextCommitsNode @internal @graphql(key: "first_commit: commits(first:1)")
-  ResponseLastCommits: ContextCommitsNode @internal @graphql(key: "last_commit: commits(last:1)")
-  ResponseNotes: ContextNotesNode @internal @graphql(key: "notes(last: 10)")
 
   #
   # scm-engine customs
   #
 
+  "All notes on this MR"
   Notes: [ContextNote!] @generated
+
+  "Information about the first commit made"
   FirstCommit: ContextCommit @generated()
+  "Information about the last commit made"
   LastCommit: ContextCommit @generated()
+  "Duration between first and last commit made"
   TimeBetweenFirstAndLastCommit: Duration @generated()
+  "Duration (from 'now') since the first commit was made"
   TimeSinceFirstCommit: Duration @generated()
+  "Duration (from 'now') since the last commit was made"
   TimeSinceLastCommit: Duration @generated()
 
+  #
+  # scm-engine internal
+  #
+
   CurrentUser: ContextUser! @generated @internal
+  ResponseLabels: ContextLabelNode @internal @graphql(key: "labels(first: 200)")
+  ResponseFirstCommits: ContextCommitsNode @internal @graphql(key: "first_commit: commits(first:1)")
+  ResponseLastCommits: ContextCommitsNode @internal @graphql(key: "last_commit: commits(last:1)")
+  ResponseNotes: ContextNotesNode @internal @graphql(key: "notes(last: 10)")
 }
 
 # https://docs.gitlab.com/ee/api/graphql/reference/#note
 type ContextNote {
+  "User who wrote the note"
+  Author: ContextUser!
+  "Content of the note"
   Body: String!
-  UpdatedAt: Time!
+  "Timestamp of the note creation"
   CreatedAt: Time!
-  Author: ContextUser!
+  "Timestamp of the note’s last activity"
+  UpdatedAt: Time!
 }
 
 # Internal only, used to de-nest connections