Update docs for /build, html and generate

Author: leoj3n

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/helpers.js

@@ -8,10 +8,11 @@ var buildHash = require("./build_hash");
 
 /**
  * @parent bit-docs-generate-html/modules
- * @module {Promise} bit-docs-generate-html/build/helpers helpers
+ * @module {Promise} bit-docs-generate-html/build/helpers
  *
- * Gets the default helpers, and helpers in the _{buildHash}/site/templates_
- * folder, and registers them with Handlebars.
+ * 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)`
  *
@@ -22,21 +23,20 @@ var buildHash = require("./build_hash");
  * 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 [bit-docs/types/docObject]
+ * currently being generated.
  *
- * A function that when called, returns the `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){
 

build/static_dist.js

@@ -13,31 +13,38 @@ var remove = Q.denodeify(fs.remove);
 
 /**
  * @parent bit-docs-generate-html/modules
- * @module {function} bit-docs-generate-html/build/static_dist staticDist
+ * @module {function} bit-docs-generate-html/build/static_dist
  *
  * Builds a static distributable which will eventually be copied to the
  * `static` folder of the generated output.
  *
- * @signature `.build.staticDist(options)`
+ * @signature `staticDist(options)`
  *
  * Builds the static distributable with the following steps:
  *
- * 1. Copies everything from _site/default/static_ to _site/static/build_.
- * 2. Copies the path in `options.dest` to _site/static/build_.
- * 3. `require`s the module at _site/static/build/build.js_.
+ * 1. Copies everything from [bit-docs-generate-html/site/default/static] to
+ * [bit-docs-generate-html/site/static/build/buildHash].
+ * 
+ * 2. Copies the path in `options.dest` to
+ * [bit-docs-generate-html/site/static/build/buildHash].
+ * 
+ * 3. `require`s the "build" module at
+ * [bit-docs-generate-html/site/static/build/buildHash/build.js].
+ * 
  * 4. Calls that "build" module function with the options and returns the
  * result.
  *
  * The "build" module is expected to build a minified distributable and copy
- * the necessary contents to _site/static/dist_ and return a promise that
- * resolves when complete.
+ * the necessary contents to
+ * [bit-docs-generate-html/site/static/dist/buildHash] and return a promise
+ * that resolves when complete.
  *
  * @param {{}} options
  *
  *   @option {Boolean} [forceBuild=false] If set to `true`, rebuilds the static
  *   bundle even if it has already been built.
  *   
- *   @option {String} dest The final destination ouput of the static
+ *   @option {String} dest The final destination output of the static
  *   distributable.
  *
  *   @option {String} static The location of static content used to overwrite or

build/templates.js

@@ -3,37 +3,38 @@ var	Q = require('q');
 var md5 = require('md5');
 var path = require('path');
 var promiseLock = require("../promise_lock");
-var queue = promiseLock(),
-	buildHash = require("./build_hash"),
-	_ = require("lodash");
+var queue = promiseLock();
+var buildHash = require("./build_hash");
+var _ = require("lodash");
 
 /**
- * @function documentjs.generators.html.build.templates
- * @parent documentjs.generators.html.build.methods
+ * @parent bit-docs-generate-html/modules
+ * @module {function} bit-docs-generate-html/build/templates
  *
- * Creates a folder with all the templates used to generate
- * the documentation.
+ * Creates a folder with all the templates used to generate the documentation.
  *
- * @signature `.build.templates(siteConfig)`
+ * @signature `build.templates(siteConfig)`
  *
- * Builds the _documentjs/site/templates_ folder with the following
- * steps:
+ * Builds the [bit-docs-generate-html/site/templates/buildHash] folder with the
+ * following steps:
  *
- * 1. Copies _documentjs/site/default/templates_ to _documentjs/site/templates_.
- * 2. Copies `siteConfig.templates` to _documentjs/site/templates_.
+ * 1. Copies [bit-docs-generate-html/site/default/templates] to
+ * [bit-docs-generate-html/site/templates/buildHash].
+ * 2. Copies `siteConfig.templates` to
+ * [bit-docs-generate-html/site/templates/buildHash].
  *
  * @param {{}} siteConfig
  *
  * siteConfig used to configure the behavior of the templates.
  *
- * @option {Boolean} [forceBuild=false] If set to `true`, rebuilds the
- * static bundle even if it has already been built.
- *
- * @option {String} [templates] The location of templates used to overwrite or
- * add to the default templates.
- *
- * @return {Promise} A promise that resolves if the static dist was successfully created.
+ *   @option {Boolean} [forceBuild=false] If set to `true`, rebuilds the static
+ *   bundle even if it has already been built.
+ *   
+ *   @option {String} [templates] The location of templates used to overwrite or
+ *   add to the default templates.
  *
+ * @return {Promise} A promise that resolves if the static dist was
+ * successfully created.
  */
 module.exports = function(siteConfig){
 

generate.js

@@ -1,22 +1,23 @@
 
-var build = require("./build/build"),
-	write = require("./write/write"),
-	Q = require("q"),
-	fs = require("fs-extra"),
-	mkdirs = Q.denodeify(fs.mkdirs),
-	Handlebars = require("handlebars");
+var build = require("./build/build");
+var write = require("./write/write");
+var Q = require("q");
+var fs = require("fs-extra");
+var mkdirs = Q.denodeify(fs.mkdirs);
+var Handlebars = require("handlebars");
 
 /**
- * @function documentjs.generators.html.generate
- * @parent documentjs.generators.html.methods
+ * @parent bit-docs-generate-html/modules
+ * @module {function} bit-docs-generate-html/generate
  *
- * Generates an HTML site for a [documentjs.process.docMap docMap]
+ * Generates an HTML site for a [bit-docs/types/docMap]
  * given configuration siteConfig.
  *
- * @signature `.generate(docMapPromise, siteConfig)`
+ * @signature `generate(docMapPromise, siteConfig)`
  *
- * @param {Promise<documentjs.process.docMap>} docMapPromise A promise that
- * contains a `docMap` created by [documentjs.process.files].
+ * @param {Promise<bit-docs/types/docMap>} docMapPromise A promise that
+ * contains a `docMap` created by [bit-docs-glob-finder/index].
+ * 
  * @param {Object} siteConfig Configuration siteConfig.
  *
  * @return {Promise} A promise that resolves when the site has been built.

html.js

@@ -1,23 +1,18 @@
 /**
- * @property {{}} documentjs.generators.html generators.html
- * @parent DocumentJS.apis.internal
+ * @parent bit-docs-generate-html/modules
+ * @module {{}} bit-docs-generate-html/html
  * 
- * @group documentjs.generators.html.properties 0 properties
- * @group documentjs.generators.html.methods 1 methods
- * @group documentjs.generators.html.defaultHelpers 2 default helpers
- * 
- * 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
  * 
- * ## Use
- * 
- *     var documentjs = require("documentjs");
- *     documentjs.process.file(...)
+ * Requires and exports these other modules:
+ * - [bit-docs-generate-html/build/build] as `build`.
+ * - [bit-docs-generate-html/write/write] as `write`.
+ * - [bit-docs-generate-html/generate] as `generate`.
  */
-
 exports.build = require("./build/build");
 exports.write = require("./write/write");
-exports.generate = require("./generate");
+exports.generate = require("./generate");