api/graph: use GraphQL descriptions for docs

api/graph/schema.graphqls

@@ -3,22 +3,28 @@
 scalar Cursor
 scalar Time
 scalar Upload
-# URL from which some secondary data may be retrieved. You must provide the
-# same Authentication header to this address as you did to the GraphQL resolver
-# which provided it. The URL is not guaranteed to be consistent for an extended
-# length of time; applications should submit a new GraphQL query each time they
-# wish to access the data at the provided URL.
+"""
+URL from which some secondary data may be retrieved. You must provide the
+same Authentication header to this address as you did to the GraphQL resolver
+which provided it. The URL is not guaranteed to be consistent for an extended
+length of time; applications should submit a new GraphQL query each time they
+wish to access the data at the provided URL.
+"""
 scalar URL
 
-# This is used to decorate fields which are only accessible with a personal
-# access token, and are not available to clients using OAuth 2.0 access tokens.
+"""
+This is used to decorate fields which are only accessible with a personal
+access token, and are not available to clients using OAuth 2.0 access tokens.
+"""
 directive @private on FIELD_DEFINITION
 
-# This used to decorate fields which are for internal use, and are not
-# available to normal API users.
+"""
+This used to decorate fields which are for internal use, and are not
+available to normal API users.
+"""
 directive @internal on FIELD_DEFINITION
 
-# Used to provide a human-friendly description of an access scope.
+"Used to provide a human-friendly description of an access scope."
 directive @scopehelp(details: String!) on ENUM_VALUE
 
 enum AccessScope {
@@ -31,18 +37,20 @@ enum AccessKind {
   RW @scopehelp(details: "read and write")
 }
 
-# Decorates fields for which access requires a particular OAuth 2.0 scope with
-# read or write access. For the meta.sr.ht API, you have access to all public
-# information without any special permissions - user profile information,
-# public keys, and so on.
+"""
+Decorates fields for which access requires a particular OAuth 2.0 scope with
+read or write access. For the meta.sr.ht API, you have access to all public
+information without any special permissions - user profile information,
+public keys, and so on.
+"""
 directive @access(scope: AccessScope!, kind: AccessKind!) on FIELD_DEFINITION | ENUM_VALUE
 
 enum Visibility {
-  # Visible to everyone, listed on your profile
+  "Visible to everyone, listed on your profile"
   PUBLIC
-  # Visible to everyone (if they know the URL), not listed on your profile
+  "Visible to everyone (if they know the URL), not listed on your profile"
   UNLISTED
-  # Not visible to anyone except those explicitly added to the access list
+  "Not visible to anyone except those explicitly added to the access list"
   PRIVATE
 }
 
@@ -51,17 +59,21 @@ type Version {
   major: Int!
   minor: Int!
   patch: Int!
-  # If this API version is scheduled for deprecation, this is the date on which
-  # it will stop working; or null if this API version is not scheduled for
-  # deprecation.
+  """
+  If this API version is scheduled for deprecation, this is the date on which
+  it will stop working; or null if this API version is not scheduled for
+  deprecation.
+  """
   deprecationDate: Time
 }
 
 interface Entity {
   id: Int!
   created: Time!
-  # The canonical name of this entity. For users, this is their username
-  # prefixed with '~'. Additional entity types will be supported in the future.
+  """
+  The canonical name of this entity. For users, this is their username
+  prefixed with '~'. Additional entity types will be supported in the future.
+  """
   canonicalName: String!
 
   pastes(cursor: Cursor): PasteCursor! @access(scope: PASTES, kind: RO)
@@ -92,47 +104,51 @@ type File {
   contents: URL!
 }
 
-# A cursor for enumerating pastes
-#
-# If there are additional results available, the cursor object may be passed
-# back into the same endpoint to retrieve another page. If the cursor is null,
-# there are no remaining results to return.
+"""
+A cursor for enumerating pastes
+
+If there are additional results available, the cursor object may be passed
+back into the same endpoint to retrieve another page. If the cursor is null,
+there are no remaining results to return.
+"""
 type PasteCursor {
   results: [Paste!]!
   cursor: Cursor
 }
 
 type Query {
-  # Returns API version information.
+  "Returns API version information."
   version: Version!
 
-  # Returns the authenticated user.
+  "Returns the authenticated user."
   me: User! @access(scope: PROFILE, kind: RO)
 
-  # Returns a specific user.
+  "Returns a specific user."
   user(username: String!): User @access(scope: PROFILE, kind: RO)
 
-  # Returns a list of pastes created by the authenticated user.
+  "Returns a list of pastes created by the authenticated user."
   pastes(cursor: Cursor): PasteCursor @access(scope: PASTES, kind: RO)
 
-  # Returns a paste by its ID.
+  "Returns a paste by its ID."
   paste(id: String!): Paste @access(scope: PASTES, kind: RO)
 }
 
 type Mutation {
-  # Creates a new paste from a list of files. The files uploaded must have a
-  # content type of text/* and must be decodable as UTF-8.
-  #
-  # Note that the web UI will replace CRLF with LF in uploads; the GraphQL API
-  # does not.
+  """
+  Creates a new paste from a list of files. The files uploaded must have a
+  content type of text/* and must be decodable as UTF-8.
+
+  Note that the web UI will replace CRLF with LF in uploads; the GraphQL API
+  does not.
+  """
   create(
     files: [Upload!]!,
     visibility: Visibility!,
   ): Paste! @access(scope: PASTES, kind: RW)
 
-  # Updates the visibility of a paste.
+  "Updates the visibility of a paste."
   update(id: String!, visibility: Visibility!): Paste @access(scope: PASTES, kind: RW)
 
-  # Deletes a paste by its ID.
+  "Deletes a paste by its ID."
   delete(id: String!): Paste @access(scope: PASTES, kind: RW)
 }