Improve documentation for types

lib/schema.js

@@ -47,6 +47,7 @@ function newTempusSchema(tempus) {
     fields: () => ({
       map: {
         type: MapType,
+        description: "Get a single jump map by name or ID",
         args: {
           name: { type: GraphQLString },
           id: { type: GraphQLInt },
@@ -55,6 +56,8 @@ function newTempusSchema(tempus) {
       },
       maps: {
         type: new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(MapType))),
+        description:
+          "Get a list of jump maps, with an optional search parameter",
         args: {
           search: { type: GraphQLString },
           start: { type: GraphQLInt },
@@ -71,27 +74,31 @@ function newTempusSchema(tempus) {
       },
       player: {
         type: PlayerType,
+        description: "Get a player by ID",
         args: {
           id: { type: new GraphQLNonNull(GraphQLInt) },
         },
         resolve: (root, args) => new Player(context, args),
       },
       record: {
         type: RecordType,
+        description: "Get a record by ID",
         args: {
           id: { type: new GraphQLNonNull(GraphQLInt) },
         },
         resolve: (root, args) => new Record(context, args),
       },
       demo: {
         type: DemoType,
+        description: "Get a demo recording by ID",
         args: {
           id: { type: new GraphQLNonNull(GraphQLInt) },
         },
         resolve: (root, args) => new Demo(context, args),
       },
       server: {
         type: ServerType,
+        description: "Get a server by ID",
         args: {
           id: { type: new GraphQLNonNull(GraphQLInt) },
         },
@@ -101,6 +108,7 @@ function newTempusSchema(tempus) {
         type: new GraphQLNonNull(
           new GraphQLList(new GraphQLNonNull(ServerType))
         ),
+        description: "Get a list of servers, with an optional search parameter",
         args: {
           search: { type: GraphQLString },
           start: { type: GraphQLInt },
@@ -118,13 +126,16 @@ function newTempusSchema(tempus) {
         },
       },
       activity: {
+        description: "Get the recent activity on the Tempus network",
         type: new GraphQLNonNull(ActivityType),
         resolve: () => new Activity(context),
       },
       players: {
         type: new GraphQLNonNull(
           new GraphQLList(new GraphQLNonNull(PlayerType))
         ),
+        description:
+          "Get a list of players, with an optional search parameter, in descending order by overall rank",
         args: {
           search: { type: GraphQLString },
           start: { type: GraphQLInt },
@@ -139,6 +150,7 @@ function newTempusSchema(tempus) {
       },
       rankings: {
         type: new GraphQLNonNull(RankingListingType),
+        description: "Get the soldier, demoman, or overall tempus rankings",
         args: {
           start: { type: GraphQLInt },
           type: { type: new GraphQLNonNull(RankingTypeEnum) },

lib/types/activity.js

@@ -12,27 +12,31 @@ export default new GraphQLObjectType({
   fields: () => ({
     bonusWrs: {
       type: new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(RecordType))),
+      description: "The recent bonus world records",
       args: {
         start: { type: GraphQLInt },
         limit: { type: GraphQLInt },
       },
     },
     courseWrs: {
       type: new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(RecordType))),
+      description: "The recent course world records",
       args: {
         start: { type: GraphQLInt },
         limit: { type: GraphQLInt },
       },
     },
     mapWrs: {
       type: new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(RecordType))),
+      description: "The recent map world records",
       args: {
         start: { type: GraphQLInt },
         limit: { type: GraphQLInt },
       },
     },
     mapTops: {
       type: new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(RecordType))),
+      description: "The recent map top times",
       args: {
         start: { type: GraphQLInt },
         limit: { type: GraphQLInt },

lib/types/class_type_enum.js

@@ -2,6 +2,8 @@ import { GraphQLEnumType } from "graphql";
 
 export default new GraphQLEnumType({
   name: "Class",
+  description:
+    "The class, either soldier or demoman. Demoman is often abbreviated as 'demo', which is different from a demo recording",
   values: {
     SOLDIER: { value: "soldier" },
     DEMOMAN: { value: "demoman" },

lib/types/demo.js

@@ -12,18 +12,50 @@ import ServerType from "./server";
 
 export default new GraphQLObjectType({
   name: "Demo",
+  description:
+    "A demo recording. Contains information about a particular server recording. Not the same as the abbreviation for demoman",
 
   fields: () => ({
-    id: { type: new GraphQLNonNull(GraphQLInt) },
-    map: { type: new GraphQLNonNull(MapType) },
-    filename: { type: GraphQLString },
-    date: { type: new GraphQLNonNull(GraphQLFloat) },
-    url: { type: GraphQLString },
-    recording: { type: new GraphQLNonNull(GraphQLBoolean) },
-    requested: { type: new GraphQLNonNull(GraphQLBoolean) },
-    expired: { type: new GraphQLNonNull(GraphQLBoolean) },
-    deleted: { type: new GraphQLNonNull(GraphQLBoolean) },
-    uploader: { type: PlayerType },
-    server: { type: new GraphQLNonNull(ServerType) },
+    id: {
+      type: new GraphQLNonNull(GraphQLInt),
+      description: "The ID of this demo",
+    },
+    map: {
+      type: new GraphQLNonNull(MapType),
+      description: "The map for this demo",
+    },
+    filename: { type: GraphQLString, description: "The filename of this demo" },
+    date: {
+      type: new GraphQLNonNull(GraphQLFloat),
+      description: "The date of this demo in unix seconds",
+    },
+    url: {
+      type: GraphQLString,
+      description: "The URL for downloading this demo, if available",
+    },
+    recording: {
+      type: new GraphQLNonNull(GraphQLBoolean),
+      description: "If this demo is currently recording",
+    },
+    requested: {
+      type: new GraphQLNonNull(GraphQLBoolean),
+      description: "If an upload of this demo has been requested",
+    },
+    expired: {
+      type: new GraphQLNonNull(GraphQLBoolean),
+      description: "If the upload of this demo has expired",
+    },
+    deleted: {
+      type: new GraphQLNonNull(GraphQLBoolean),
+      description: "If the upload of this demo has been deleted",
+    },
+    uploader: {
+      type: PlayerType,
+      description: "The player who uploaded this demo",
+    },
+    server: {
+      type: new GraphQLNonNull(ServerType),
+      description: "The server where this demo was recorded",
+    },
   }),
 });

lib/types/map.js

@@ -14,29 +14,44 @@ import ClassTypeEnum from "./class_type_enum";
 
 const Author = new GraphQLObjectType({
   name: "Author",
+  description: "An author of a map",
 
   fields: () => ({
-    id: { type: new GraphQLNonNull(GraphQLInt) },
-    name: { type: new GraphQLNonNull(GraphQLString) },
+    id: {
+      type: new GraphQLNonNull(GraphQLInt),
+      description: "The ID of the author",
+    },
+    name: {
+      type: new GraphQLNonNull(GraphQLString),
+      description: "The name of the author",
+    },
     mapCount: {
       type: new GraphQLNonNull(GraphQLInt),
+      description: "The number of maps this author has created",
       resolve: (author) => author.map_count,
     },
-    player: { type: PlayerType },
+    player: {
+      type: PlayerType,
+      description:
+        "The author's Player, if the author is a registered Tempus player",
+    },
   }),
 });
 
 const MapVideos = new GraphQLObjectType({
   name: "MapVideos",
+  description: "The videos with playthroughs of a map",
 
   fields: () => ({
     soldier: {
       type: GraphQLString,
+      description: "The URL for the video of a soldier playthrough of a map",
       resolve: (videos) =>
         videos.soldier && `https://youtube.com/watch?v=${videos.soldier}`,
     },
     demoman: {
       type: GraphQLString,
+      description: "The URL for the video of a demoman playthrough of a map",
       resolve: (videos) =>
         videos.demoman && `https://youtube.com/watch?v=${videos.demoman}`,
     },
@@ -45,37 +60,48 @@ const MapVideos = new GraphQLObjectType({
 
 const Zones = new GraphQLObjectType({
   name: "Zones",
+  description: "The zones for a map",
 
   fields: () => ({
     bonus: {
       type: new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(ZoneType))),
+      description: "The bonus zones for a map",
     },
     bonusEnd: {
       type: new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(ZoneType))),
+      description: "The bonus end zones for a map",
     },
     checkpoint: {
       type: new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(ZoneType))),
+      description: "The checkpoint zones for a map",
     },
     course: {
       type: new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(ZoneType))),
+      description: "The course zones for a map",
     },
     courseEnd: {
       type: new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(ZoneType))),
+      description: "The course end zones for a map",
     },
     linear: {
       type: new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(ZoneType))),
+      description: "The linear zones for a map",
     },
     map: {
       type: new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(ZoneType))),
+      description: "The map zones for a map",
     },
     mapEnd: {
       type: new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(ZoneType))),
+      description: "The end zones for a map",
     },
     misc: {
       type: new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(ZoneType))),
+      description: "The miscellaneous zones for a map",
     },
     trick: {
       type: new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(ZoneType))),
+      description: "The trick zones for a map",
     },
   }),
 });
@@ -85,16 +111,34 @@ export default new GraphQLObjectType({
   description: "A jump map",
 
   fields: () => ({
-    id: { type: new GraphQLNonNull(GraphQLString) },
-    name: { type: new GraphQLNonNull(GraphQLString) },
+    id: {
+      type: new GraphQLNonNull(GraphQLString),
+      description: "The ID of the map",
+    },
+    name: {
+      type: new GraphQLNonNull(GraphQLString),
+      description: "The name of the map",
+    },
     authors: {
       type: new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(Author))),
+      description: "The authors of this map",
+    },
+    videos: {
+      type: new GraphQLNonNull(MapVideos),
+      description: "Videos showing playthroughs of this map",
+    },
+    tiers: {
+      type: new GraphQLNonNull(Tiers),
+      description: "The tiers of this map",
+    },
+    zones: {
+      type: new GraphQLNonNull(Zones),
+      description: "The zones of this map",
     },
-    videos: { type: new GraphQLNonNull(MapVideos) },
-    tiers: { type: new GraphQLNonNull(Tiers) },
-    zones: { type: new GraphQLNonNull(Zones) },
     records: {
       type: new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(RecordType))),
+      description:
+        "Player records on this map, filterable by class and zone. Later records can be fetched with a non-empty start argument",
       args: {
         zoneType: { type: ZoneTypeEnum },
         zoneId: { type: GraphQLInt },
@@ -105,6 +149,8 @@ export default new GraphQLObjectType({
     },
     record: {
       type: RecordType,
+      description:
+        "Fetch a single record on this map by providing the player and class, and optionally a zone. Without a zone, the player's map record will be fetched",
       args: {
         zoneType: { type: ZoneTypeEnum },
         zoneId: { type: GraphQLInt },
@@ -114,6 +160,7 @@ export default new GraphQLObjectType({
     },
     wr: {
       type: RecordType,
+      description: "Fetch the world record on this map by class",
       args: {
         class: { type: new GraphQLNonNull(ClassTypeEnum) },
       },