documentation and cleanup

closes #4

Author: bmuenzenmeyer

README.md

@@ -1 +1,39 @@
-# plugin-node-tab
+![license](https://img.shields.io/github/license/pattern-lab/plugin-node-tab.svg)
+[![npm](https://img.shields.io/npm/v/plugin-node-tab.svg)](https://www.npmjs.com/package/plugin-node-tab)
+[![Gitter](https://img.shields.io/gitter/room/pattern-lab/php.svg)](https://gitter.im/pattern-lab/php)
+
+# Tab Plugin for Pattern Lab Node
+
+The Tab Plugin allows Pattern Lab Node users to see sibling files next to a pattern in the filesystem, displaying them as additional tabs alongside the template and HTML tabs in both the Style Guide frontend and the single-pattern info modal.
+
+## Installation
+
+To add the Tab Plugin to your project using [npm](http://npmjs.com/) type:
+
+    npm install plugin-node-tab --save
+
+Or add it directly to your project's `package.json` file and run `npm install`
+
+Post installation, the plugin will prompt you for what filetypes you want to add tabs for.
+
+```
+$ Specify filetype(s) to create a tab for. Separate multiple filetypes with a space, pipe or comma. Example: js css >>>
+```
+
+## Expected Structure
+
+With the Tab Plugin installed, you can now accompany pattern template files with the file types of your choice and expect Pattern Lab to show them as tabs. The file structure would be similar to that of `pattern.json` or `pattern.md` files, except that it will be `pattern.<<type>>`.
+
+For example, if we added a` css` tab:
+
+```
+./_patterns/foo/bar
+├── pattern.mustache (the pattern template)
+├── pattern.md (optional pattern-specific documentation and metadata)
+├── pattern.json (optional pattern-specific data)
+└── pattern.css (the tab you added.)
+```
+
+## Enabling / Disabling the Plugin
+
+After install, you may manually enable or disable the plugin by removing it from the `patternlab-config.json` file. Installation added a key called `plugin-node-tab` to it. In the future this will be possible via CLI.

dist/js/plugin-node-tab.js

@@ -1,8 +1,12 @@
 var PluginTab = {
 
+  /**
+   * The function defined as the onready callback within the plugin configuration. 
+   */
   init: function () {
 
     //placeholder that will be replaced during configuation
+    //most plugins could probably just implement logic here instead.
     /*SNIPPETS*/
 
   }

index.js

@@ -14,17 +14,19 @@ function onPatternIterate(patternlab, pattern) {
 
 /**
  * Define what events you wish to listen to here
+ * For a full list of events - check out https://github.com/pattern-lab/patternlab-node/wiki/Creating-Plugins#events
  * @param patternlab - global data store which has the handle to the event emitter
    */
 function registerEvents(patternlab) {
-
-  //TODO: list all possible events
+  //register our handler at the appropriate time of execution
   patternlab.events.on('patternlab-pattern-write-end', onPatternIterate);
 }
 
 /**
 * A single place to define the frontend configuration
-  */
+* This configuration is outputted to the frontend explicitly as well as included in the plugins object.
+*
+*/
 function getPluginFrontendConfig() {
   return {
     'name':'pattern-lab\/' + pluginName,
@@ -37,7 +39,7 @@ function getPluginFrontendConfig() {
 }
 
 /**
-* The entry point for the plugin. You should not have to alter this code.
+* The entry point for the plugin. You should not have to alter this code much under many circumstances.
 * Instead, alter getPluginFrontendConfig() and registerEvents() methods
   */
 function pluginInit(patternlab) {

src/tab-loader.js

@@ -4,8 +4,15 @@ const fs = require('fs-extra'),
   path = require('path'),
   fileTypes = require('./../package.json').fileTypes;
 
+/**
+ * The backend method that is called during the patternlab-pattern-write-end event.
+ * Responsible for looking for a companion filetype file alongside a pattern file and outputting it if found.
+ * @param patternlab - the global data store
+ * @param pattern - the pattern object being iterated over
+ */
 function findTab(patternlab, pattern) {
 
+  //exit if either of these two parameters are missing
   if (!patternlab) {
     console.error('plugin-node-tab: patternlab object not provided to findTab');
     process.exit(1);
@@ -19,6 +26,7 @@ function findTab(patternlab, pattern) {
   //derive the custom filetype paths from the pattern relPath
   var customFileTypePath = path.join(patternlab.config.paths.source.patterns, pattern.relPath);
 
+  //loop through all configured types
   for (let i = 0; i < fileTypes.length; i++) {
 
     customFileTypePath = customFileTypePath.substr(0, customFileTypePath.lastIndexOf(".")) + '.' + fileTypes[i];
@@ -30,30 +38,26 @@ function findTab(patternlab, pattern) {
       try {
         var tabFileNameStats = fs.statSync(tabFileName);
       } catch (err) {
-        //not a file
+        //not a file - move on quietly
       }
       if (tabFileNameStats && tabFileNameStats.isFile()) {
         if (patternlab.config.debug) {
           console.log('plugin-node-tab: copied pattern-specific custom file for ' + pattern.patternPartial);
         }
+
+        //copy the file to our output target if found
         fs.copySync(tabFileName, customFileTypeOutputPath);
       } else {
+
+        //otherwise write nothing to the same location - this prevents GET errors on the tab.
         fs.outputFileSync(customFileTypeOutputPath, '');
       }
     }
     catch (err) {
       console.log('plugin-node-tab:There was an error parsing sibling JSON for ' + pattern.relPath);
       console.log(err);
     }
-
-
-
-
   }
-
-
-
-
 }
 
 module.exports = findTab;