graphql: enhance GraphQL schema documentation for mutations and queri…

…es (#4154)

* docs: enhance GraphQL schema documentation for mutations and queries

* graphql: update UpdateRotationInput and add scalar types with descriptions

* regen

graphql2/graph/_Mutation.graphqls

@@ -18,16 +18,24 @@ type Mutation {
 
   testContactMethod(id: ID!): Boolean!
 
-  # Updates the status for multiple alerts given the list of alertIDs and the status they want to be updated to.
+  """
+  Updates the status for multiple alerts given the list of alertIDs and the status they want to be updated to.
+  """
   updateAlerts(input: UpdateAlertsInput!): [Alert!]
 
-  # Updates the fields for a rotation given the rotationID, also updates ordering of and number of users for the rotation.
+  """
+  Updates the fields for a rotation given the rotationID, also updates ordering of and number of users for the rotation.
+  """
   updateRotation(input: UpdateRotationInput!): Boolean!
 
-  # Escalates multiple alerts given the list of alertIDs.
+  """
+  Escalates multiple alerts given the list of alertIDs.
+  """
   escalateAlerts(input: [Int!]): [Alert!]
 
-  # Updates the favorite status of a target.
+  """
+  Updates the favorite status of a target.
+  """
   setFavorite(input: SetFavoriteInput!): Boolean!
 
   updateService(input: UpdateServiceInput!): Boolean!
@@ -38,10 +46,11 @@ type Mutation {
 
   createAlert(input: CreateAlertInput!): Alert
 
-  # closeMatchingAlert is used to close an alert without knowing it's ID.
-  #
-  # This allows stateless upstream systems to close alerts without needing to
-  # store the alert ID.
+  """
+  closeMatchingAlert is used to close an alert without knowing its ID.
+
+  This allows stateless upstream systems to close alerts without needing to store the alert ID.
+  """
   closeMatchingAlert(input: CloseMatchingAlertInput!): Boolean!
 
   setAlertNoiseReason(input: SetAlertNoiseReasonInput!): Boolean!

graphql2/graph/_Query.graphqls

@@ -3,124 +3,190 @@ type Query {
 
   experimentalFlags: [ID!]!
 
-  # Returns the list of recent messages.
+  """
+  Returns the list of recent messages.
+  """
   messageLogs(input: MessageLogSearchOptions): MessageLogConnection!
   debugMessages(input: DebugMessagesInput): [DebugMessage!]!
     @deprecated(reason: "debugMessages is deprecated. Use messageLogs instead.")
 
-  # Returns the user with the given ID. If no ID is specified,
-  # the current user is implied.
+  """
+  Returns the user with the given ID. If no ID is specified,
+  the current user is implied.
+  """
   user(id: ID): User
 
-  # Returns a list of users who's name or email match search string.
+  """
+  Returns a list of users who's name or email match search string.
+  """
   users(
     input: UserSearchOptions
     first: Int = 15
     after: String = ""
     search: String = ""
   ): UserConnection!
 
-  # Returns a single alert with the given ID.
+  """
+  Returns a single alert with the given ID.
+  """
   alert(id: Int!): Alert
 
-  # Returns a paginated list of alerts.
+  """
+  Returns a paginated list of alerts.
+  """
   alerts(input: AlertSearchOptions): AlertConnection!
 
-  # Returns a single service with the given ID.
+  """
+  Returns a single service with the given ID.
+  """
   service(id: ID!): Service
 
-  # Returns a single integration key with the given ID.
+  """
+  Returns a single integration key with the given ID.
+  """
   integrationKey(id: ID!): IntegrationKey
 
-  # Returns a heartbeat monitor with the given ID
+  """
+  Returns a heartbeat monitor with the given ID.
+  """
   heartbeatMonitor(id: ID!): HeartbeatMonitor
 
-  # Returns a paginated list of services.
+  """
+  Returns a paginated list of services.
+  """
   services(input: ServiceSearchOptions): ServiceConnection!
 
-  # Returns a single rotation with the given ID.
+  """
+  Returns a single rotation with the given ID.
+  """
   rotation(id: ID!): Rotation
 
-  # Returns a paginated list of rotations.
+  """
+  Returns a paginated list of rotations.
+  """
   rotations(input: RotationSearchOptions): RotationConnection!
 
   calcRotationHandoffTimes(
     input: CalcRotationHandoffTimesInput
   ): [ISOTimestamp!]!
 
-  # Returns a single schedule with the given ID.
+  """
+  Returns a single schedule with the given ID.
+  """
   schedule(id: ID!): Schedule
 
-  # Returns the public information of a calendar subscription
+  """
+  Returns the public information of a calendar subscription
+  """
   userCalendarSubscription(id: ID!): UserCalendarSubscription
 
-  # Returns a paginated list of schedules.
+  """
+  Returns a paginated list of schedules.
+  """
   schedules(input: ScheduleSearchOptions): ScheduleConnection!
 
-  # Returns a single escalation policy with the given ID.
+  """
+  Returns a single escalation policy with the given ID.
+  """
   escalationPolicy(id: ID!): EscalationPolicy
 
-  # Returns a paginated list of escalation policies.
+  """
+  Returns a paginated list of escalation policies.
+  """
   escalationPolicies(
     input: EscalationPolicySearchOptions
   ): EscalationPolicyConnection!
 
-  # Returns the list of auth subjects for the given provider ID.
+  """
+  Returns the list of auth subjects for the given provider ID.
+  """
   authSubjectsForProvider(
     first: Int = 15
     after: String = ""
     providerID: ID!
   ): AuthSubjectConnection!
 
-  # Returns a paginated list of time zones.
+  """
+  Returns a paginated list of time zones.
+  """
   timeZones(input: TimeZoneSearchOptions): TimeZoneConnection!
 
-  # Allows searching for assigned labels.
+  """
+  Allows searching for assigned labels.
+  """
   labels(input: LabelSearchOptions): LabelConnection!
 
-  # Allows searching for label keys.
+  """
+  Allows searching for label keys.
+  """
   labelKeys(input: LabelKeySearchOptions): StringConnection!
 
-  # Allows searching for label values.
+  """
+  Allows searching for label values.
+  """
   labelValues(input: LabelValueSearchOptions): StringConnection!
 
-  # Allows searching for integration keys.
+  """
+  Allows searching for integration keys.
+  """
   integrationKeys(input: IntegrationKeySearchOptions): IntegrationKeyConnection!
 
-  # Allows searching for user overrides.
+  """
+  Allows searching for user overrides.
+  """
   userOverrides(input: UserOverrideSearchOptions): UserOverrideConnection!
 
-  # Returns a single user override with the given ID.
+  """
+  Returns a single user override with the given ID.
+  """
   userOverride(id: ID!): UserOverride
 
-  # Returns public server configuration values. If all is set to true,
-  # then all values are returned (must be admin).
+  """
+  Returns public server configuration values. If all is set to true,
+  then all values are returned (must be admin).
+  """
   config(all: Boolean): [ConfigValue!]!
 
-  # Returns configuration hints (must be admin).
+  """
+  Returns configuration hints (must be admin).
+  """
   configHints: [ConfigHint!]!
 
   integrationKeyTypes: [IntegrationKeyTypeInfo!]!
 
-  # Returns configuration limits
+  """
+  Returns configuration limits
+  """
   systemLimits: [SystemLimit!]!
 
-  # Returns the message status
+  """
+  Returns the message status
+  """
   debugMessageStatus(input: DebugMessageStatusInput!): DebugMessageStatusInfo!
 
-  # Returns a contact method with the given ID.
+  """
+  Returns a contact method with the given ID.
+  """
   userContactMethod(id: ID!): UserContactMethod
 
-  # Returns the list of Slack channels available to the current user.
+  """
+  Returns the list of Slack channels available to the current user.
+  """
   slackChannels(input: SlackChannelSearchOptions): SlackChannelConnection!
 
-  # Returns a Slack channel with the given ID.
+  """
+  Returns a Slack channel with the given ID.
+  """
   slackChannel(id: ID!): SlackChannel
 
-  # Returns the list of Slack user groups available.
+  """
+  Returns the list of Slack user groups available.
+  """
   slackUserGroups(input: SlackUserGroupSearchOptions): SlackUserGroupConnection!
 
-  # Returns a Slack user group with the given ID.
+  """
+  Returns a Slack user group with the given ID.
+  """
   slackUserGroup(id: ID!): SlackUserGroup
 
   generateSlackAppManifest: String!