Merge branch 'graphql-docs' into main

src/server/types/AppearanceLayer.js

@@ -17,12 +17,14 @@ const typeDefs = gql`
 
   # Cache for 1 week (unlikely to change)
   type AppearanceLayer @cacheControl(maxAge: 604800) {
-    # The DTI ID. Guaranteed unique across all layers of all types.
+    "The DTI ID. Guaranteed unique across all layers of all types."
     id: ID!
 
-    # The Neopets ID. Guaranteed unique across layers of the _same_ type, but
+    """
-    # not of different types. That is, it's allowed and common for an item
+    The Neopets ID. Guaranteed unique across layers of the _same_ type, but
-    # layer and a pet layer to have the same remoteId.
+    not of different types. That is, it's allowed and common for an item
+    layer and a pet layer to have the same remoteId.
+    """
     remoteId: ID!
 
     zone: Zone!

src/server/types/ClosetList.js

@@ -12,10 +12,15 @@ const typeDefs = gql`
     id: ID!
     name: String
 
-    # A user-customized description. May contain Markdown and limited HTML.
+    """
+    A user-customized description. May contain Markdown and limited HTML.
+    WARNING: If you're using this in an application, you MUST ensure that the
+             content is rendered safely! Do not render this as HTML unless you
+             are confident that you've sanitized it appropriately.
+    """
     description: String
 
-    # Whether this is a list of items they own, or items they want.
+    "Whether this is a list of items they own, or items they want."
     ownsOrWantsItems: OwnsOrWants!
 
     # Each user has a "default list" of items they own/want. When users click
@@ -30,8 +35,10 @@ const typeDefs = gql`
   }
 
   extend type Mutation {
-    # Edit the metadata of a closet list. Requires the current user to own the
+    """
-    # list, or for the correct supportSecret to be provided.
+    Edit the metadata of a closet list. Requires the current user to own the
+    list, or for the correct supportSecret to be provided.
+    """
     editClosetList(
       closetListId: ID!
       name: String!

src/server/types/Item.js

@@ -15,101 +15,129 @@ const typeDefs = gql`
     thumbnailUrl: String!
     rarityIndex: Int!
 
-    # Whether this item comes from the NC Mall.
+    "Whether this item comes from the NC Mall."
     isNc: Boolean!
 
-    # Whether this item comes from a paintbrush.
+    "Whether this item comes from a paintbrush."
     isPb: Boolean!
 
-    # When this item was first added to DTI. ISO 8601 string, or null if the
+    """
-    # item was added so long ago that we don't have this field!
+    When this item was first added to DTI. ISO 8601 string, or null if the
+    item was added so long ago that we don't have this field!
+    """
     createdAt: String
 
-    # This item's capsule trade value as text, according to wakaguide.com, as a
+    """
-    # human-readable string. Will be null if the value is not known, or if
+    This item's capsule trade value as text, according to wakaguide.com, as a
-    # there's an error connecting to the data source.
+    human-readable string. Will be null if the value is not known, or if
+    there's an error connecting to the data source.
+    """
     wakaValueText: String @cacheControl(maxAge: ${oneHour})
 
     currentUserOwnsThis: Boolean! @cacheControl(scope: PRIVATE)
     currentUserWantsThis: Boolean! @cacheControl(scope: PRIVATE)
 
-    # How many users are offering/seeking this in their public trade lists.
+    """
-    # Excludes users that seem relatively inactive.
+    How many users are offering/seeking this in their public trade lists.
+    Excludes users that seem relatively inactive.
+    """
     numUsersOfferingThis: Int! @cacheControl(maxAge: ${oneHour})
     numUsersSeekingThis: Int! @cacheControl(maxAge: ${oneHour})
 
-    # The trades available for this item, grouped by offering vs seeking.
+    "The trades available for this item, grouped by offering vs seeking."
     tradesOffering: [ItemTrade!]! @cacheControl(maxAge: 0)
     tradesSeeking: [ItemTrade!]! @cacheControl(maxAge: 0)
 
-    # How this item appears on the given species/color combo. If it does not
+    """
-    # fit the pet, we'll return an empty ItemAppearance with no layers.
+    How this item appears on the given species/color combo. If it does not
+    fit the pet, we'll return an empty ItemAppearance with no layers.
+    """
     appearanceOn(speciesId: ID!, colorId: ID!): ItemAppearance! @cacheControl(maxAge: 1, staleWhileRevalidate: ${oneDay})
 
-    # This is set manually by Support users, when the pet is only for e.g.
+    """
-    # Maraquan pets, and our usual auto-detection isn't working. We provide
+    This is set manually by Support users, when the pet is only for e.g.
-    # this for the Support UI; it's not very helpful for most users, because it
+    Maraquan pets, and our usual auto-detection isn't working. We provide
-    # can be empty even if the item _has_ an auto-detected special color.
+    this for the Support UI; it's not very helpful for most users, because it
+    can be empty even if the item _has_ an auto-detected special color.
+    """
     manualSpecialColor: Color @cacheControl(maxAge: 0)
 
-    # This is set manually by Support users, when the item _seems_ to fit all
+    """
-    # pets the same because of its zones, but it actually doesn't - e.g.,
+    This is set manually by Support users, when the item _seems_ to fit all
-    # the Dug Up Dirt Foreground actually looks different for each body. We
+    pets the same because of its zones, but it actually doesn't - e.g.,
-    # provide this for the Support UI; it's not very helpful for most users,
+    the Dug Up Dirt Foreground actually looks different for each body. We
-    # because it's only used at modeling time. This value does not change how
+    provide this for the Support UI; it's not very helpful for most users,
-    # layer data from this API should be interpreted!
+    because it's only used at modeling time. This value does not change how
+    layer data from this API should be interpreted!
+    """
     explicitlyBodySpecific: Boolean! @cacheControl(maxAge: 0)
 
-    # This is set manually by Support users, when the item is from the NC Mall
+    """
-    # but isn't correctly labeled as r500 on Neopets.com. When this is true,
+    This is set manually by Support users, when the item is from the NC Mall
-    # it sets isNc to be true as well, regardless of rarityIndex.
+    but isn't correctly labeled as r500 on Neopets.com. When this is true,
+    it sets isNc to be true as well, regardless of rarityIndex.
+    """
     isManuallyNc: Boolean!
 
-    # Get the species that we need modeled for this item for the given color.
+    """
-    #
+    Get the species that we need modeled for this item for the given color.
-    # NOTE: Most color IDs won't be accepted here. Either pass the ID of a
+    
-    #       major special color like Baby (#6), or leave it blank for standard
+    NOTE: Most color IDs won't be accepted here. Either pass the ID of a
-    #       bodies like Blue, Green, Red, etc.
+          major special color like Baby (#6), or leave it blank for standard
+          bodies like Blue, Green, Red, etc.
+    """
     speciesThatNeedModels(colorId: ID): [Species!]! @cacheControl(maxAge: 1, staleWhileRevalidate: ${oneHour})
 
-    # Return a single ItemAppearance for this item. It'll be for the species
+    """
-    # with the smallest ID for which we have item appearance data, and a basic
+    Return a single ItemAppearance for this item. It'll be for the species
-    # color. We use this on the item page, to initialize the preview section.
+    with the smallest ID for which we have item appearance data, and a basic
-    # (You can find out which species this is for by going through the body
+    color. We use this on the item page, to initialize the preview section.
-    # field on ItemAppearance!)
+    (You can find out which species this is for by going through the body
-    #
+    field on ItemAppearance!)
-    # There's also optional fields preferredSpeciesId and preferredColorId, to
+    
-    # request a certain species or color if possible. We'll try to match each,
+    There's also optional fields preferredSpeciesId and preferredColorId, to
-    # with precedence to species first; then fall back to the canonical values.
+    request a certain species or color if possible. We'll try to match each,
-    #
+    with precedence to species first; then fall back to the canonical values.
-    # Note that the exact choice of color doesn't usually affect this field,
+    
-    # because ItemAppearance is per-body rather than per-color. It's most
+    Note that the exact choice of color doesn't usually affect this field,
-    # relevant for special colors like Baby or Mutant. But the
+    because ItemAppearance is per-body rather than per-color. It's most
-    # canonicalAppearance on the Body type _does_ use the preferred color more
+    relevant for special colors like Baby or Mutant. But the
-    # precisely!
+    canonicalAppearance on the Body type _does_ use the preferred color more
+    precisely!
+    """
     canonicalAppearance(preferredSpeciesId: ID, preferredColorId: ID): ItemAppearance @cacheControl(maxAge: 1, staleWhileRevalidate: ${oneWeek})
  
-    # All zones that this item occupies, for at least one body. That is, it's
+    """
-    # a union of zones for all of its appearances! We use this for overview
+    All zones that this item occupies, for at least one body. That is, it's
-    # info about the item.
+    a union of zones for all of its appearances! We use this for overview
+    info about the item.
+    """
     allOccupiedZones: [Zone!]! @cacheControl(maxAge: ${oneHour})
 
-    # The zones this item restricts. Turns out, even though we offer this on
+    """
-    # ItemAppearance for consistency, this is static across all appearances.
+    The zones this item restricts. Turns out, even though we offer this on
+    ItemAppearance for consistency, this is static across all appearances.
+    """
     restrictedZones: [Zone!]! @cacheControl(maxAge: ${oneHour}, staleWhileRevalidate: ${oneWeek})
 
-    # All bodies that this item is compatible with. Note that this might return
+    """
-    # the special representsAllPets body, e.g. if this is just a Background!
+    All bodies that this item is compatible with. Note that this might return
-    # Deprecated: Impress 2020 now uses compatibleBodiesAndTheirZones.
+    the special representsAllPets body, e.g. if this is just a Background!
+    Deprecated: Impress 2020 now uses compatibleBodiesAndTheirZones.
+    """
     compatibleBodies: [Body!]! @cacheControl(maxAge: 1, staleWhileRevalidate: ${oneWeek})
 
-    # All bodies that this item is compatible with, and the zones this item
+    """
-    # occupies for that body. Note that this might return the special
+    All bodies that this item is compatible with, and the zones this item
-    # representsAllPets body, e.g. if this is just a Background!
+    occupies for that body. Note that this might return the special
+    representsAllPets body, e.g. if this is just a Background!
+    """
     compatibleBodiesAndTheirZones: [BodyAndZones!]! @cacheControl(maxAge: 1, staleWhileRevalidate: ${oneWeek})
 
-    # All appearances for this item. Used in Support tools, to show and manage
+    """
-    # how this item fits every pet body.
+    All appearances for this item. Used in Support tools, to show and manage
+    how this item fits every pet body.
+    """
     allAppearances: [ItemAppearance!]!
   }
 

src/server/types/Outfit.js

@@ -16,14 +16,16 @@ const typeDefs = gql`
     closetedItems: [Item!]!
     creator: User
 
-    # When this outfit was created. ISO 8601 string.
+    "When this outfit was created. ISO 8601 string."
     createdAt: String!
 
-    # When this outfit was last updated. ISO 8601 string.
+    "When this outfit was last updated. ISO 8601 string."
     updatedAt: String!
 
-    # This is a convenience field: you could query this from the combination of
+    """
-    # petAppearance and wornItems, but this gets you it in one shot!
+    This is a convenience field: you could query this from the combination of
+    petAppearance and wornItems, but this gets you it in one shot!
+    """
     itemAppearances: [ItemAppearance!]!
   }
 
@@ -34,8 +36,10 @@ const typeDefs = gql`
 
   extend type Mutation {
     saveOutfit(
-      id: ID # Optional, is null when saving new outfits.
+      "Optional, is null when saving new outfits."
-      name: String # Optional, server may fill in a placeholder.
+      id: ID
+      "Optional, server may fill in a placeholder."
+      name: String
       speciesId: ID!
       colorId: ID!
       pose: Pose!

src/server/types/Pet.js

@@ -11,10 +11,14 @@ const typeDefs = gql`
     petAppearance: PetAppearance!
     wornItems: [Item!]!
 
-    species: Species! # to be deprecated? can use petAppearance? 🤔
+    "to be deprecated? can use petAppearance? 🤔"
-    color: Color! # to be deprecated? can use petAppearance? 🤔
+    species: Species!
-    pose: Pose! # to be deprecated? can use petAppearance? 🤔
+    "to be deprecated? can use petAppearance? 🤔"
-    items: [Item!]! # deprecated alias for wornItems
+    color: Color!
+    "to be deprecated? can use petAppearance? 🤔"
+    pose: Pose!
+    "deprecated alias for wornItems"
+    items: [Item!]!
   }
 
   extend type Query {

src/server/types/PetAppearance.js

@@ -16,7 +16,7 @@ const typeDefs = gql`
     name: String!
     isStandard: Boolean!
 
-    # All SpeciesColorPairs of this color.
+    "All SpeciesColorPairs of this color."
     appliedToAllCompatibleSpecies: [SpeciesColorPair!]! @cacheControl(maxAge: 1, staleWhileRevalidate: ${oneDay})
   }
 
@@ -24,13 +24,17 @@ const typeDefs = gql`
     id: ID!
     name: String!
 
-    # A PetAppearance that has this species. Prefers Blue (or the optional
+    """
-    # preferredColorId), and happy poses.
+    A PetAppearance that has this species. Prefers Blue (or the optional
+    preferredColorId), and happy poses.
+    """
     canonicalAppearance(preferredColorId: ID): PetAppearance
 
-    # The bodyId for PetAppearances that use this species and a standard color.
+    """
-    # We use this to preload the standard body IDs, so that items stay when
+    The bodyId for PetAppearances that use this species and a standard color.
-    # switching between standard colors.
+    We use this to preload the standard body IDs, so that items stay when
+    switching between standard colors.
+    """
     standardBodyId: ID!
   }
 

src/server/types/User.js

@@ -13,20 +13,26 @@ const typeDefs = gql`
     itemsTheyOwn: [Item!]!
     itemsTheyWant: [Item!]!
 
-    # These items represent potential trade matches. We use this as a preview
+    """
-    # in the trade list table.
+    These items represent potential trade matches. We use this as a preview
+    in the trade list table.
+    """
     itemsTheyOwnThatCurrentUserWants: [Item!]!
     itemsTheyWantThatCurrentUserOwns: [Item!]!
 
-    # When this user last updated any of their trade lists, as an ISO 8601
+    """
-    # timestamp.
+    When this user last updated any of their trade lists, as an ISO 8601
+    timestamp.
+    """
     lastTradeActivity: String!
 
-    # This user's outfits. Returns an empty list if the current user is not
+    """
-    # authorized to see them.
+    This user's outfits. Returns an empty list if the current user is not
+    authorized to see them.
+    """
     outfits: [Outfit!]!
 
-    # This user's email address. Requires the correct supportSecret to view.
+    "This user's email address. Requires the correct supportSecret to view."
     emailForSupportUsers(supportSecret: String!): String!
   }