Comments and docs

src/loaders.js

@@ -5,13 +5,16 @@ import { toPlural } from './types/helpers'
 const debug = require('debug')('graphbrainz:loaders')
 
 export default function createLoaders (client) {
+  // All loaders share a single LRU cache that will remember 8192 responses,
+  // each cached for 1 day.
   const cache = LRUCache({
     max: 8192,
-    maxAge: 24 * 60 * 60 * 1000, // 1 day.
+    maxAge: 24 * 60 * 60 * 1000,
     dispose (key) {
       debug(`Removed '${key}' from cache.`)
     }
   })
+  // Make the cache Map-like.
   cache.delete = cache.del
   cache.clear = cache.reset
 
@@ -20,6 +23,8 @@ export default function createLoaders (client) {
       const [ entityType, id, params ] = key
       return client.lookup(entityType, id, params).then(entity => {
         if (entity) {
+          // Store the entity type so we can determine what type of object this
+          // is elsewhere in the code.
           entity.entityType = entityType
         }
         return entity
@@ -35,6 +40,8 @@ export default function createLoaders (client) {
       const [ entityType, params ] = key
       return client.browse(entityType, params).then(list => {
         list[toPlural(entityType)].forEach(entity => {
+          // Store the entity type so we can determine what type of object this
+          // is elsewhere in the code.
           entity.entityType = entityType
         })
         return list
@@ -50,6 +57,8 @@ export default function createLoaders (client) {
       const [ entityType, query, params ] = key
       return client.search(entityType, query, params).then(list => {
         list[toPlural(entityType)].forEach(entity => {
+          // Store the entity type so we can determine what type of object this
+          // is elsewhere in the code.
           entity.entityType = entityType
         })
         return list

src/resolvers.js

@@ -66,6 +66,8 @@ export function browseResolver () {
     params.type = params.type.map(formatValue)
     params.status = params.status.map(formatValue)
     return loaders.browse.load([singularName, params]).then(list => {
+      // Grab the list, offet, and count from the response and use them to build
+      // a Relay connection object.
       const {
         [pluralName]: arraySlice,
         [`${singularName}-offset`]: sliceStart,
@@ -99,6 +101,7 @@ export function searchResolver () {
 export function relationshipResolver () {
   return (source, args, context, info) => {
     const targetType = toDashed(toSingular(info.fieldName)).replace('-', '_')
+    // There's no way to filter these at the API level, so do it here.
     const relationships = source.filter(rel => {
       if (rel['target-type'] !== targetType) {
         return false

src/types/enums.js

@@ -49,8 +49,8 @@ record company. (Most releases will fit into this category.)`,
     PROMOTION: {
       name: 'Promotion',
       description: `A giveaway release or a release intended to promote an
-upcoming official release. (e.g. prerelease albums or releases included with a
+upcoming official release, e.g. prerelease albums or releases included with a
-magazine)`,
+magazine.`,
       value: 'Promotion'
     },
     BOOTLEG: {
@@ -116,7 +116,7 @@ by one or more artists.`,
     SOUNDTRACK: {
       name: 'Soundtrack',
       description: `A soundtrack is the musical score to a movie, TV series,
-stage show, computer game etc.`,
+stage show, computer game, etc.`,
       value: 'Soundtrack'
     },
     SPOKENWORD: {
@@ -167,7 +167,7 @@ While mixtapes are generally DJ-mixed, they are distinct from commercial DJ
 mixes (which are usually deemed compilations) and are defined by having a
 significant proportion of new material, including original production or
 original vocals over top of other artists’ instrumentals. They are distinct from
-demos in that they are designed for release directly to the public and fans; not
+demos in that they are designed for release directly to the public and fans, not
 to labels.`,
       value: 'Mixtape/Street'
     },

src/types/helpers.js

@@ -58,10 +58,11 @@ export function fieldWithID (name, config = {}) {
   const isPlural = config.type instanceof GraphQLList
   const singularName = isPlural ? toSingular(name) : name
   const idName = isPlural ? `${singularName}IDs` : `${name}ID`
+  const s = isPlural ? 's' : ''
   const idConfig = {
     type: isPlural ? new GraphQLList(MBID) : MBID,
-    description: `The MBID${isPlural ? 's' : ''} associated with the
+    description: `The MBID${s} associated with the value${s} of the \`${name}\`
-value${isPlural ? 's' : ''} of the \`${name}\` field.`,
+field.`,
     resolve: getHyphenated
   }
   return {

src/types/release-event.js

@@ -4,7 +4,7 @@ import Area from './area'
 
 export default new GraphQLObjectType({
   name: 'ReleaseEvent',
-  description: `Date on which a release was released in a country/region with a
+  description: `Date on which a release was issued in a country/region with a
 particular label, catalog number, barcode, and what release format was used.`,
   fields: () => ({
     area: { type: Area },