Add missing Oxford commas, add descriptions for enums, render interface fields

docs/schema.md

@@ -226,7 +226,7 @@ type ArtistConnection {
 
 # [Artist credits](https://musicbrainz.org/doc/Artist_Credits)
 # indicate who is the main credited artist (or artists) for releases, release
-# groups, tracks and recordings, and how they are credited. They consist of
+# groups, tracks, and recordings, and how they are credited. They consist of
 # artists, with (optionally) their names as credited in the specific release,
 # track, etc., and join phrases between them.
 type ArtistCredit {
@@ -796,7 +796,7 @@ type PageInfo {
   endCursor: String
 }
 
-# A [place](https://musicbrainz.org/doc/Place) is a venue, studio
+# A [place](https://musicbrainz.org/doc/Place) is a venue, studio,
 # or other place where music is performed, recorded, engineered, etc.
 type Place implements Node, Entity {
   # The ID of an object
@@ -1487,6 +1487,8 @@ type ReleaseGroupEdge {
   score: Int
 }
 
+# A type used to describe release groups, e.g. album, single, EP,
+# etc.
 enum ReleaseGroupType {
   # An album, perhaps better defined as a “Long Play” (LP)
   # release, generally consists of previously unreleased material (unless this type
@@ -1568,6 +1570,8 @@ enum ReleaseGroupType {
   NAT
 }
 
+# A type used to describe the status of releases, e.g. official,
+# bootleg, etc.
 enum ReleaseStatus {
   # Any release officially sanctioned by the artist and/or their
   # record company. (Most releases will fit into this category.)
@@ -1901,4 +1905,4 @@ type WorkEdge {
   # these results were found through a search.
   score: Int
 }
-```
+```

docs/types.md

@@ -604,7 +604,7 @@ ignoring pagination.</td>
 
 [Artist credits](https://musicbrainz.org/doc/Artist_Credits)
 indicate who is the main credited artist (or artists) for releases, release
-groups, tracks and recordings, and how they are credited. They consist of
+groups, tracks, and recordings, and how they are credited. They consist of
 artists, with (optionally) their names as credited in the specific release,
 track, etc., and join phrases between them.
 
@@ -1664,7 +1664,7 @@ Information about pagination in a connection.
 
 ### Place
 
-A [place](https://musicbrainz.org/doc/Place) is a venue, studio
+A [place](https://musicbrainz.org/doc/Place) is a venue, studio,
 or other place where music is performed, recorded, engineered, etc.
 
 <table><thead>
@@ -3769,6 +3769,9 @@ these results were found through a search.</td>
 
 ### ReleaseGroupType
 
+A type used to describe release groups, e.g. album, single, EP,
+etc.
+
 <table><thead>
   <th align="left">Value</th>
   <th align="left">Description</th>
@@ -3872,6 +3875,9 @@ reference use rather than for general public release.</td>
 
 ### ReleaseStatus
 
+A type used to describe the status of releases, e.g. official,
+bootleg, etc.
+
 <table><thead>
   <th align="left">Value</th>
   <th align="left">Description</th>
@@ -3947,11 +3953,35 @@ A web address.
 
 ## Interfaces
 
+
 ### Entity
 
 An entity in the MusicBrainz schema.
 
+<table><thead>
+  <th align="left">Field&nbsp;/&nbsp;Argument</th>
+  <th align="left">Type</th>
+  <th align="left">Description</th>
+</thead><tbody>
+  <tr>
+    <td valign="top"><strong>mbid</strong></td>
+    <td valign="top"><a href="#mbid">MBID</a>!</td>
+    <td>The MBID of the entity.</td>
+  </tr>
+</tbody></table>
+
 ### Node
 
 An object with an ID
 
+<table><thead>
+  <th align="left">Field&nbsp;/&nbsp;Argument</th>
+  <th align="left">Type</th>
+  <th align="left">Description</th>
+</thead><tbody>
+  <tr>
+    <td valign="top"><strong>id</strong></td>
+    <td valign="top"><a href="#id">ID</a>!</td>
+    <td>The id of the object.</td>
+  </tr>
+</tbody></table>

package.json

@@ -19,7 +19,7 @@
     "build": "npm run build:lib && npm run update-schema && npm run build:docs",
     "build:docs": "npm run build:docs:readme && npm run build:docs:schema && npm run build:docs:types",
     "build:docs:readme": "doctoc --title \"## Contents\" README.md",
-    "build:docs:schema": "printf '# GraphQL Schema\\n\\n%s' \"$(npm run -s print-schema:md)\" > docs/schema.md",
+    "build:docs:schema": "printf '# GraphQL Schema\\n\\n%s\n' \"$(npm run -s print-schema:md)\" > docs/schema.md",
     "build:docs:types": "babel-node scripts/render-types.js > docs/types.md",
     "build:lib": "babel --out-dir lib src",
     "clean": "npm run clean:lib",

schema.json

@@ -2130,7 +2130,7 @@
         {
           "kind": "OBJECT",
           "name": "ArtistCredit",
-          "description": "[Artist credits](https://musicbrainz.org/doc/Artist_Credits)\nindicate who is the main credited artist (or artists) for releases, release\ngroups, tracks and recordings, and how they are credited. They consist of\nartists, with (optionally) their names as credited in the specific release,\ntrack, etc., and join phrases between them.",
+          "description": "[Artist credits](https://musicbrainz.org/doc/Artist_Credits)\nindicate who is the main credited artist (or artists) for releases, release\ngroups, tracks, and recordings, and how they are credited. They consist of\nartists, with (optionally) their names as credited in the specific release,\ntrack, etc., and join phrases between them.",
           "fields": [
             {
               "name": "artist",
@@ -2177,7 +2177,7 @@
         {
           "kind": "ENUM",
           "name": "ReleaseGroupType",
-          "description": null,
+          "description": "A type used to describe release groups, e.g. album, single, EP,\netc.",
           "fields": null,
           "inputFields": null,
           "interfaces": null,
@@ -2284,7 +2284,7 @@
         {
           "kind": "ENUM",
           "name": "ReleaseStatus",
-          "description": null,
+          "description": "A type used to describe the status of releases, e.g. official,\nbootleg, etc.",
           "fields": null,
           "inputFields": null,
           "interfaces": null,
@@ -5892,7 +5892,7 @@
         {
           "kind": "OBJECT",
           "name": "Place",
-          "description": "A [place](https://musicbrainz.org/doc/Place) is a venue, studio\nor other place where music is performed, recorded, engineered, etc.",
+          "description": "A [place](https://musicbrainz.org/doc/Place) is a venue, studio,\nor other place where music is performed, recorded, engineered, etc.",
           "fields": [
             {
               "name": "id",

scripts/render-types.js

@@ -1,6 +1,12 @@
 import marked from 'marked'
 const schema = require('../schema.json').data.__schema
 
+// Ideally, we could just spit out the existing description Markdown everywhere
+// and leave it to be rendered by whatever processes the output. But some
+// Markdown renderers, including GitHub's, don't process Markdown if it's within
+// an HTML tag. So in some places (like descriptions of the types themselves) we
+// just output the raw description. In other places, like table cells, we need
+// to output pre-rendered Markdown, otherwise GitHub won't interpret it.
 marked.setOptions({
   breaks: false
 })
@@ -110,7 +116,6 @@ console.log('\n## Objects')
 objects.forEach(type => renderObject(type))
 
 console.log('\n## Enums')
-
 enums.forEach(type => {
   console.log(`\n### ${type.name}\n`)
   if (type.description) {
@@ -130,7 +135,6 @@ enums.forEach(type => {
 })
 
 console.log('\n## Scalars\n')
-
 scalars.forEach(type => {
   console.log(`### ${type.name}\n`)
   if (type.description) {
@@ -139,10 +143,4 @@ scalars.forEach(type => {
 })
 
 console.log('\n## Interfaces\n')
-
-interfaces.forEach(type => {
-  console.log(`### ${type.name}\n`)
-  if (type.description) {
-    console.log(`${type.description}\n`)
-  }
-})
+interfaces.forEach(type => renderObject(type))

src/types/artist-credit.js

@@ -5,7 +5,7 @@ export default new GraphQLObjectType({
   name: 'ArtistCredit',
   description: `[Artist credits](https://musicbrainz.org/doc/Artist_Credits)
 indicate who is the main credited artist (or artists) for releases, release
-groups, tracks and recordings, and how they are credited. They consist of
+groups, tracks, and recordings, and how they are credited. They consist of
 artists, with (optionally) their names as credited in the specific release,
 track, etc., and join phrases between them.`,
   fields: () => ({

src/types/enums.js

@@ -2,6 +2,8 @@ import { GraphQLEnumType } from 'graphql/type'
 
 export const ArtistType = new GraphQLEnumType({
   name: 'ArtistType',
+  description: `A type used to describe artists, e.g. person, group, character,
+etc.`,
   values: {
     PERSON: {
       name: 'Person',
@@ -39,6 +41,8 @@ distinctive name.`,
 
 export const ReleaseStatus = new GraphQLEnumType({
   name: 'ReleaseStatus',
+  description: `A type used to describe the status of releases, e.g. official,
+bootleg, etc.`,
   values: {
     OFFICIAL: {
       name: 'Official',
@@ -70,6 +74,8 @@ translation/transliteration purposes.`,
 
 export const ReleaseGroupType = new GraphQLEnumType({
   name: 'ReleaseGroupType',
+  description: `A type used to describe release groups, e.g. album, single, EP,
+etc.`,
   values: {
     ALBUM: {
       name: 'Album',

src/types/place.js

@@ -34,7 +34,7 @@ export const Coordinates = new GraphQLObjectType({
 
 const Place = new GraphQLObjectType({
   name: 'Place',
-  description: `A [place](https://musicbrainz.org/doc/Place) is a venue, studio
+  description: `A [place](https://musicbrainz.org/doc/Place) is a venue, studio,
 or other place where music is performed, recorded, engineered, etc.`,
   interfaces: () => [Node, Entity],
   fields: () => ({