feat(docs): Add jsdoc output to public API and events

Author: bmuenzenmeyer

.prettierignore

@@ -0,0 +1,2 @@
+./scripts/api.handlebars
+./scripts/events.handlebars

core/index.js

@@ -15,6 +15,7 @@ const packageInfo = require('../package.json');
 const path = require('path');
 const updateNotifier = require('update-notifier');
 
+const events = require('./events');
 const logger = require('./lib/log');
 const PatternGraph = require('./lib/pattern_graph').PatternGraph;
 const CompileState = require('./lib/object_factory').CompileState;
@@ -43,9 +44,9 @@ updateNotifier({
 }).notify();
 
 /**
- * Returns the standardized default config
+ * Returns the standardized default config used to run Pattern Lab. This method can be called statically or after instantiation.
  *
- * @return {object} Returns the object representation of the patternlab-config.json
+ * @return {object} Returns the object representation of the `patternlab-config.json`
  */
 const getDefaultConfig = function() {
   return defaultConfig;
@@ -175,7 +176,7 @@ const patternlab_module = function(config) {
   }
 
   function buildPatterns(deletePatternDir, additionalData) {
-    patternlab.events.emit('patternlab-build-pattern-start', patternlab);
+    patternlab.events.emit(events.PATTERNLAB_BUILD_PATTERN_START, patternlab);
 
     //
     // CHECK INCREMENTAL BUILD GRAPH
@@ -207,7 +208,7 @@ const patternlab_module = function(config) {
         .processAllPatternsIterative(paths.source.patterns)
         .then(() => {
           patternlab.events.emit(
-            'patternlab-pattern-iteration-end',
+            events.PATTERNLAB_PATTERN_ITERATION_END,
             patternlab
           );
 
@@ -332,27 +333,30 @@ const patternlab_module = function(config) {
 
   return {
     /**
-     * logs current version
+     * Logs current version to standard output
      *
-     * @returns {void} current patternlab-node version as defined in package.json, as console output
+     * @returns {void} current patternlab-node version as defined in `package.json`
      */
     version: function() {
       return patternlab.logVersion();
     },
 
     /**
-     * return current version
+     * Returns current version
      *
-     * @returns {string} current patternlab-node version as defined in package.json, as string
+     * @returns {string} current patternlab-node version as defined in `package.json`, as string
      */
     v: function() {
       return patternlab.getVersion();
     },
 
     /**
-     * build patterns, copy assets, and construct ui
+     * Builds patterns, copies assets, and constructs user interface
      *
      * @param {object} options an object used to control build behavior
+     * @param {bool} options.cleanPublic whether or not to delete the configured output location (usually `public/`) before build
+     * @param {object} options.data additional data to be merged with global data prior to build
+     * @param {bool} options.watch whether or not Pattern Lab should watch configured `source/` directories for changes to rebuild
      * @returns {Promise} a promise fulfilled when build is complete
      */
     build: function(options) {
@@ -393,16 +397,16 @@ const patternlab_module = function(config) {
     },
 
     /**
-     * Returns the standardized default config
+     * Returns the standardized default config used to run Pattern Lab. This method can be called statically or after instantiation.
      *
-     * @return {object} Returns the object representation of the patternlab-config.json
+     * @return {object} Returns the object representation of the `patternlab-config.json`
      */
     getDefaultConfig: function() {
       return getDefaultConfig();
     },
 
     /**
-     * returns all file extensions supported by installed PatternEngines
+     * Returns all file extensions supported by installed PatternEngines
      *
      * @returns {Array<string>} all supported file extensions
      */
@@ -411,7 +415,7 @@ const patternlab_module = function(config) {
     },
 
     /**
-     * logs usage
+     * Logs usage to standard output
      *
      * @returns {void} pattern lab API usage, as console output
      */
@@ -420,7 +424,7 @@ const patternlab_module = function(config) {
     },
 
     /**
-     * install plugin already available via `node_modules/`
+     * Installs plugin already available via `node_modules/`
      *
      * @param {string} pluginName name of plugin
      * @returns {void}
@@ -430,7 +434,7 @@ const patternlab_module = function(config) {
     },
 
     /**
-     * fetches starterkit repos from pattern-lab github org that contain 'starterkit' in their name
+     * Fetches starterkit repositories from pattern-lab github org that contain 'starterkit' in their name
      *
      * @returns {Promise} Returns an Array<{name,url}> for the starterkit repos
      */
@@ -439,7 +443,7 @@ const patternlab_module = function(config) {
     },
 
     /**
-     * load starterkit already available via `node_modules/`
+     * Loads starterkit already available via `node_modules/`
      *
      * @param {string} starterkitName name of starterkit
      * @param {boolean} clean whether or not to delete contents of source/ before load
@@ -450,9 +454,11 @@ const patternlab_module = function(config) {
     },
 
     /**
-     * build patterns only, leaving existing public files intact
+     * Builds patterns only, leaving existing user interface files intact
      *
      * @param {object} options an object used to control build behavior
+     * @param {bool} options.cleanPublic whether or not to delete the configured output location (usually `public/`) before build
+     * @param {object} options.data additional data to be merged with global data prior to build
      * @returns {Promise} a promise fulfilled when build is complete
      */
     patternsonly: function(options) {
@@ -469,10 +475,13 @@ const patternlab_module = function(config) {
     },
 
     /**
-     * build patterns, copy assets, and construct ui, watch source files, and serve locally
+     * Build patterns, copies assets, and constructs user interface. Watches configured `source/` directories, and serves all output locally
      *
-     * @param {object} options an object used to control build, copy, and serve behavior
-     * @returns {Promise} TODO: validate
+     * @param {object} options an object used to control build behavior
+     * @param {bool} options.cleanPublic whether or not to delete the configured output location (usually `public/`) before build
+     * @param {object} options.data additional data to be merged with global data prior to build
+     * @param {bool} options.watch **ALWAYS OVERRIDDEN to `true`** whether or not Pattern Lab should watch configured `source/` directories for changes to rebuild
+     * @returns {Promise} a promise fulfilled when build is complete
      */
     serve: function(options) {
       options.watch = true;

core/lib/asset_copy.js

@@ -2,6 +2,8 @@
 const _ = require('lodash');
 const path = require('path');
 const process = require('process');
+
+const events = require('./events');
 const logger = require('./log');
 
 let copy = require('recursive-copy'); // eslint-disable-line prefer-const
@@ -43,7 +45,7 @@ const asset_copier = () => {
   const copyFile = (p, dest, options) => {
     copy(p, dest, options).on(copy.events.COPY_FILE_COMPLETE, () => {
       logger.debug(`Moved ${p} to ${dest}`);
-      options.emitter.emit('patternlab-asset-change', {
+      options.emitter.emit(events.PATTERNLAB_PATTERN_ASSET_CHANGE, {
         file: p,
         dest: dest,
       });
@@ -163,17 +165,17 @@ const asset_copier = () => {
         //watch for changes and rebuild
         globalWatcher
           .on('addDir', p => {
-            patternlab.events.emit('patternlab-global-change', {
+            patternlab.events.emit(events.PATTERNLAB_GLOBAL_CHANGE, {
               file: p,
             });
           })
           .on('add', p => {
-            patternlab.events.emit('patternlab-global-change', {
+            patternlab.events.emit(events.PATTERNLAB_GLOBAL_CHANGE, {
               file: p,
             });
           })
           .on('change', p => {
-            patternlab.events.emit('patternlab-global-change', {
+            patternlab.events.emit(events.PATTERNLAB_GLOBAL_CHANGE, {
               file: p,
             });
           });
@@ -207,17 +209,17 @@ const asset_copier = () => {
         //watch for changes and rebuild
         patternWatcher
           .on('addDir', p => {
-            patternlab.events.emit('patternlab-pattern-change', {
+            patternlab.events.emit(events.PATTERNLAB_PATTERN_CHANGE, {
               file: p,
             });
           })
           .on('add', p => {
-            patternlab.events.emit('patternlab-pattern-change', {
+            patternlab.events.emit(events.PATTERNLAB_PATTERN_CHANGE, {
               file: p,
             });
           })
           .on('change', p => {
-            patternlab.events.emit('patternlab-pattern-change', {
+            patternlab.events.emit(events.PATTERNLAB_PATTERN_CHANGE, {
               file: p,
             });
           });

core/lib/events.js

@@ -0,0 +1,74 @@
+'use strict';
+
+/**
+ * All Pattern Lab Events
+ * @module Events
+ */
+
+/**
+ * @alias module:Events
+ */
+const EVENTS = Object.freeze({
+  /**
+   * @desc Emitted before any logic run inside `build()`, which is the entry point for single builds, pattern-only builds, run singly or when watched.
+   * @property {object} patternlab - global data store
+   *
+   */
+  PATTERNLAB_BUILD_PATTERN_START: 'patternlab-build-pattern-start',
+
+  /**
+   * @desc Emitted after patterns are iterated over to gather data about them. Right before Pattern Lab processes and renders patterns into HTML
+   * @property {object} patternlab - global data store
+   */
+  PATTERNLAB_PATTERN_ITERATION_END: 'patternlab-pattern-iteration-end',
+
+  /**
+   * @desc Emitted after global `data.json` and `listitems.json` are read, and the supporting Pattern Lab templates are loaded into memory (header, footer, patternSection, patternSectionSubType, viewall). Right before patterns are iterated over to gather data about them.
+   * @property {object} patternlab - global data store
+   */
+  PATTERNLAB_BUILD_GLOBAL_DATA_END: 'patternlab-build-global-data-end',
+
+  /**
+   * @desc Emitted before all data is merged prior to a Pattern's render. Global `data.json` is merged with any pattern `.json`. Global `listitems.json` is merged with any pattern `.listitems.json`.
+   * @property {object} patternlab - global data store
+   * @property {Pattern} pattern - current pattern
+   * @see {@link https://github.com/pattern-lab/patternlab-node/blob/master/core/lib/object_factory.js#L16|Pattern}
+   */
+  PATTERNLAB_PATTERN_BEFORE_DATA_MERGE: 'patternlab-pattern-before-data-merge',
+
+  /**
+   * @desc Emitted before a pattern's template, HTML, and encoded HTML files are written to their output location
+   * @property {object} patternlab - global data store
+   * @property {Pattern} pattern - current pattern
+   * @see {@link https://github.com/pattern-lab/patternlab-node/blob/master/core/lib/object_factory.js#L16|Pattern}
+   */
+  PATTERNLAB_PATTERN_WRITE_BEGIN: 'patternlab-pattern-write-begin',
+
+  /**
+   * @desc Emitted after a pattern's template, HTML, and encoded HTML files are written to their output location
+   * @property {object} patternlab - global data store
+   * @property {Pattern} pattern - current pattern
+   * @see {@link https://github.com/pattern-lab/patternlab-node/blob/master/core/lib/object_factory.js#L16|Pattern}
+   */
+  PATTERNLAB_PATTERN_WRITE_END: 'patternlab-pattern-write-end',
+
+  /**
+   * @desc Invoked when a watched asset changes. Assets include anything in `source/` that is not under `['root', 'patterns', 'data', 'meta', 'annotations', 'patternlabFiles']` which are blacklisted for specific copying.
+   * @property {object} fileInfo - `{file: 'path/to/file.css', dest: 'path/to/destination'}`
+   */
+  PATTERNLAB_PATTERN_ASSET_CHANGE: 'patternlab-pattern-asset-change',
+
+  /**
+   * @desc Invoked when a watched global file changes. These are files within the directories specified in `['data', 'meta']`paths.
+   * @property {object} fileInfo - `{file: 'path/to/file.ext'}`
+   */
+  PATTERNLAB_GLOBAL_CHANGE: 'patternlab-global-change',
+
+  /**
+   * @desc Invoked when a pattern changes.
+   * @property {object} fileInfo - `{file: 'path/to/file.ext'}`
+   */
+  PATTERNLAB_PATTERN_CHANGE: 'patternlab-pattern-change',
+});
+
+module.exports = EVENTS;

core/lib/patternlab.js

@@ -8,6 +8,7 @@ const cleanHtml = require('js-beautify').html;
 const inherits = require('util').inherits;
 const pm = require('./plugin_manager');
 const packageInfo = require('../../package.json');
+const events = require('./events');
 const buildListItems = require('./buildListItems');
 const dataLoader = require('./data_loader')();
 const logger = require('./log');
@@ -230,7 +231,7 @@ module.exports = class PatternLab {
 
     buildListItems(this);
 
-    this.events.emit('patternlab-build-global-data-end', this);
+    this.events.emit(events.PATTERNLAB_BUILD_GLOBAL_DATA_END, this);
   }
 
   setCacheBust() {
@@ -360,7 +361,11 @@ module.exports = class PatternLab {
     pattern.patternLineageEExists =
       pattern.patternLineageExists || pattern.patternLineageRExists;
 
-    this.events.emit('patternlab-pattern-before-data-merge', this, pattern);
+    this.events.emit(
+      events.PATTERNLAB_PATTERN_BEFORE_DATA_MERGE,
+      this,
+      pattern
+    );
 
     //render the pattern, but first consolidate any data we may have
     let allData;
@@ -485,12 +490,16 @@ module.exports = class PatternLab {
           // WRITE FILES
           ///////////////
 
-          self.events.emit('patternlab-pattern-write-begin', self, pattern);
+          self.events.emit(
+            events.PATTERNLAB_PATTERN_WRITE_BEGIN,
+            self,
+            pattern
+          );
 
           //write the compiled template to the public patterns directory
           self.writePatternFiles(headHTML, pattern, footerHTML);
 
-          self.events.emit('patternlab-pattern-write-end', self, pattern);
+          self.events.emit(events.PATTERNLAB_PATTERN_WRITE_END, self, pattern);
 
           // Allows serializing the compile state
           self.graph.node(pattern).compileState = pattern.compileState =