Merge pull request #38 from bit-docs/docs

Document stuff in /build

Author: justinbmeyer

.gitignore

@@ -1,3 +1,4 @@
+package-lock.json
 node_modules
 site/static/
 site/static/build/

bit-docs.js

@@ -12,21 +12,41 @@ var mergeOnto = function(prop, dest, source){
 };
 
 /**
+ * @parent plugins
  * @module {function} bit-docs-generate-html
  * @group bit-docs-generate-html/modules modules
- * @parent plugins
+ * @group bit-docs-generate-html/static static
+ * @group bit-docs-generate-html/templates templates
+ * @group bit-docs-generate-html/generated generated
+ * @group bit-docs-generate-html/types types
  *
- * @description Generates HTML for a docMap.  Supports plugins.
+ * @description Generates HTML for a docMap and handles the `html` hook.
  *
  * @body
  *
- * TBD
+ * This plugin registers onto these hooks:
+ *   - `tags`
+ *   - `generator`
+ * 
+ * Registering the `tags` hook adds the `@templaterender` tag.
+ * 
+ * Registering the `generator` hook makes it so this plugin can generate the
+ * HTML output from the provided [bit-docs/types/docMap]. The entry point for
+ * this generator is [bit-docs-generate-html/html].
+ * 
+ * This plugin handles the `html` hook, which allows other plugins to hook into
+ * the generation process, to do things like include their own static assets,
+ * or provide their own mustache templates.
+ * 
+ * This plugin provides a default set of mustache templates and static assets.
+ * These mustache templates and less styles can be copied over into a theme
+ * plugin and customized. Any custom mustache template will override a default
+ * of the same name.
  */
-
 module.exports = function(bitDocs){
     bitDocs.register("generator", generator);
 
-	bitDocs.register("tags", tags);
+    bitDocs.register("tags", tags);
 
     bitDocs.handle("html", function(siteConfig, htmlConfig) {
         if(!siteConfig.html) {
@@ -42,5 +62,5 @@ module.exports = function(bitDocs){
         mergeOnto("staticDist", html, htmlConfig);
         mergeOnto("static", html, htmlConfig);
         mergeOnto("templates", html, htmlConfig);
-	});
+    });
 };

build/build.js

@@ -1,21 +1,20 @@
 /**
- * @property {{}} documentjs.generators.html.build
- * @parent documentjs.generators.html.properties
+ * @parent bit-docs-generate-html/modules
+ * @module {{}} bit-docs-generate-html/build/build
  * 
- * @group documentjs.generators.html.build.methods 0 methods
- * @group documentjs.generators.html.build.types 1 types
- * 
- * A collection of helpers used to build and compile the templates
- * used to render each [documentjs.process.docObject docObject] into
- * HTML and build the static JS and CSS used by that HTML.
+ * A collection of helpers used to build and compile the templates used to
+ * render each [bit-docs/types/docObject] into HTML and build the static JS and
+ * CSS used by that HTML.
  * 
  * @body
  * 
+ * Requires and exports these other modules:
+ * - [bit-docs-generate-html/build/renderer] as `renderer`.
+ * - [bit-docs-generate-html/build/static_dist] as `staticDist`.
+ * - [bit-docs-generate-html/build/templates] as `templates`.
+ * - [bit-docs-generate-html/build/helpers] as `helpers`.
  */
-
-
-
 exports.renderer = require("./renderer");
 exports.staticDist = require("./static_dist");
 exports.templates = require("./templates");
-exports.helpers = require("./helpers");
+exports.helpers = require("./helpers");

build/build_hash.js

@@ -1,29 +1,32 @@
 var md5 = require('md5');
 
 /**
- * @function documentjs.generators.html.build.buildHash
- * @parent documentjs.generators.html.build.methods
+ * @parent bit-docs-generate-html/modules
+ * @module {function} bit-docs-generate-html/build/build_hash
  * 
  * Returns a unique hash for the options that control the build.
  * 
- * @signature `.build.buildHash(options)`
+ * @signature `buildHash(options)`
  * 
  * @param {{}} options Options that might change the characteristic of the build:
  * 
- * @option {Boolean} [minifyBuild=true] If set to `false` the build will not 
- * be minified. This behavior should be implemented by the "build" module.
+ *   @option {Boolean} [minifyBuild=true] If set to `false` the build will not be
+ *   minified. This behavior should be implemented by the "build" module.
+ *   
+ *   @option {Boolean} [devBuild=false] If set to `true` the build will not be
+ *   built and copied in "development" mode.
+ *   
+ *   @option {String} static The location of static content used to overwrite or
+ *   add to the default static content.
+ *   
+ *   @option {String} [templates] The location of templates used to overwrite or
+ *   add to the default templates.
  * 
- * @option {Boolean} [devBuild=false] If set to `true` the build will not be built
- * and copied in "development" mode.
- * 
- * @option {String} static The location of static content used to overwrite or
- * add to the default static content.
- * 
- * @option {String} [templates] The location of templates used to overwrite or
- * add to the default templates.
+ * @return {String} a hash that represents this build.
  * 
+ * @body
  * 
- * @return {String} a hash that represents this build.
+ * The generated hash will be something like `917c51373c902dc4a003c7fd949774c5`.
  */
 module.exports = function(options){
 	var values = {};

build/builder.md

@@ -1,48 +1,47 @@
-
-var getDefaultHelpers = require("./make_default_helpers"),
-	_ = require("lodash");
+var getDefaultHelpers = require("./make_default_helpers");
+var _ = require("lodash");
 var fsx = require('../fs_extras');
 var path = require('path');
 var md5 = require("md5");
-var Handlebars = require("handlebars"),
-	buildHash = require("./build_hash");
+var Handlebars = require("handlebars");
+var buildHash = require("./build_hash");
+
 /**
- * @function documentjs.generators.html.build.helpers
- * @parent documentjs.generators.html.build.methods
- *
- * Gets the default helpers and helpers in the _documentjs/site/templates_ folder and
- * registers them with Handlebars.
+ * @parent bit-docs-generate-html/modules
+ * @module {Promise} bit-docs-generate-html/build/helpers
  *
- * @signature `.build.helpers(buildTemplatesPromise, docMap, options, getCurrent)`
+ * Gets the default helpers, and helpers in the
+ * [bit-docs-generate-html/site/templates/buildHash] folder, and registers them
+ * with Handlebars.
+ * 
+ * @signature `build.helpers(buildTemplatesPromise, docMap, options, getCurrent)`
  *
  * Registers helpers
  *
- *
  * @param {Promise<Handlebars>} buildTemplatesPromise The result of calling
- * [documentjs.generators.html.build.templates]. Building the helpers
- * must happen after the templates have been copied over. Passing this
- * argument enforces that.
+ * [bit-docs-generate-html/build/templates]. Building the helpers must happen
+ * after the templates have been copied over. Passing this argument enforces
+ * that.
  *
- * @param {documentjs.process.docMap} docMap The docMap which contains all
- * docObjects that will be documented.
+ * @param {bit-docs/types/docMap} docMap The [bit-docs/types/docMap] which
+ * contains all [bit-docs/types/docObject]s that will be documented.
  *
  * @param {Object} options
  *
+ * @param {function():bit-docs/types/docObject} getCurrent
  *
- * @param {function():documentjs.process.docObject} getCurrent
- *
- * A function that when called, returns the `docObject` currently being
- * generated.
+ * A function that when called, returns the [bit-docs/types/docObject]
+ * currently being generated.
  *
- * @return {Promise} A promise that resolves when helpers have been added to Handlebars.
+ * @return {Promise} A promise that resolves when helpers have been added to
+ * Handlebars.
  *
  * @body
- *
  */
 module.exports = function(buildTemplatesPromise, docMap, options, getCurrent){
 
 	return buildTemplatesPromise.then(function(OtherHandlebars){
-		// get the default heleprs
+		// get the default helpers
 		var helpers = getDefaultHelpers(docMap,options,getCurrent, OtherHandlebars);
 
 		var templatesPath = path.join('site/templates', buildHash(options) );
@@ -73,8 +72,4 @@ module.exports = function(buildTemplatesPromise, docMap, options, getCurrent){
 
 	});
 
-
-
-
-
 };