From 2dfd2aa88d41994afb1f9f5bdca95dc2631e8495 Mon Sep 17 00:00:00 2001 From: Brian Beck Date: Tue, 29 Nov 2016 18:18:50 -0800 Subject: [PATCH] Add missing Oxford commas, add descriptions for enums, render interface fields --- docs/schema.md | 10 +++++++--- docs/types.md | 34 ++++++++++++++++++++++++++++++++-- package.json | 2 +- schema.json | 8 ++++---- scripts/render-types.js | 16 +++++++--------- src/types/artist-credit.js | 2 +- src/types/enums.js | 6 ++++++ src/types/place.js | 2 +- 8 files changed, 59 insertions(+), 21 deletions(-) diff --git a/docs/schema.md b/docs/schema.md index 9427b8c..21dc614 100644 --- a/docs/schema.md +++ b/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 } -``` \ No newline at end of file +``` diff --git a/docs/types.md b/docs/types.md index 89f166c..89c7d3c 100644 --- a/docs/types.md +++ b/docs/types.md @@ -604,7 +604,7 @@ ignoring pagination. [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. @@ -3769,6 +3769,9 @@ these results were found through a search. ### ReleaseGroupType +A type used to describe release groups, e.g. album, single, EP, +etc. +
@@ -3872,6 +3875,9 @@ reference use rather than for general public release. ### ReleaseStatus +A type used to describe the status of releases, e.g. official, +bootleg, etc. +
Value Description
@@ -3947,11 +3953,35 @@ A web address. ## Interfaces + ### Entity An entity in the MusicBrainz schema. +
Value Description
+ + + + + + + + + +
Field / ArgumentTypeDescription
mbidMBID!The MBID of the entity.
+ ### Node An object with an ID + + + + + + + + + + +
Field / ArgumentTypeDescription
idID!The id of the object.
diff --git a/package.json b/package.json index 812f3ab..c81686b 100644 --- a/package.json +++ b/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", diff --git a/schema.json b/schema.json index dd96ecf..fa9e7d0 100644 --- a/schema.json +++ b/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", diff --git a/scripts/render-types.js b/scripts/render-types.js index b114f56..a5bd893 100644 --- a/scripts/render-types.js +++ b/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)) diff --git a/src/types/artist-credit.js b/src/types/artist-credit.js index 9926ba3..cdaf3c6 100644 --- a/src/types/artist-credit.js +++ b/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: () => ({ diff --git a/src/types/enums.js b/src/types/enums.js index 38b3637..d0e66e4 100644 --- a/src/types/enums.js +++ b/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', diff --git a/src/types/place.js b/src/types/place.js index 20447ac..f7caf64 100644 --- a/src/types/place.js +++ b/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: () => ({