Merge pull request #11 from bit-docs/docs

docs

Author: justinbmeyer

bit-docs-js.md

@@ -0,0 +1,56 @@
+@parent plugins
+@module bit-docs-js
+@group bit-docs-js/types types
+@group bit-docs-js/tags tags
+@group bit-docs-js/templates templates
+@group bit-docs-js/static static
+@group bit-docs-js/modules modules
+
+@description Plugin to process `.js` files and help document JavaScript code.
+
+@body
+
+## Use this plugin
+
+Add this plugin to your project `package.json`:
+
+```json
+{
+  "name": "my-project",
+  ---snip---
+  "bit-docs": {
+    "dependencies": {
+      ---snip---
+      "bit-docs-js": "*",
+      ---snip---
+    },
+    ---snip---
+  }
+}
+```
+
+Once added, this plugin allows you to document `.js` files like:
+
+```js
+/**
+ * @module {{}} example/settings settings
+ * @parent example
+ * @option {String} environment Production, development, or staging.
+ * @option {Number} requestTimeout How long to wait between requests.
+ */
+export default {
+    environment: "production",
+    requestTimeout: 100
+}
+```
+
+ Using [bit-docs-js/templates/signature.mustache signature.mustache] in the
+ [bit-docs-generate-html/site/default/templates/content.mustache default theme],
+ this example renders like:
+
+<img src="https://user-images.githubusercontent.com/990216/30096690-7e01d47c-929f-11e7-9eac-bbe97f4f1a7f.png" width="50%" />
+
+### See next
+
+- Back-end hooks: [bit-docs-js/bit-docs].
+- Front-end assets: [bit-docs-js/index.js].

bit-docs.js

@@ -3,35 +3,51 @@ var processJavaScript = require("./process/javascript");
 var path = require("path");
 
 /**
- * @module {function} bit-docs-js
- * @parent plugins
- * @group bit-docs-js/tags tags
+ * @parent bit-docs-js/modules
+ * @module {bit-docs/types/plugin} bit-docs-js/bit-docs
  *
- * @description Tags, templates, and basic styles for JavaScript.
- *
- * @param {Object} [bitDocs] The configuration object passed by `bit-docs` at
- * runtime. 
+ * @description Register hooks to add tags, templates, and basic styles useful
+ * for documenting JavaScript.
+ * 
+ * @signature `jsPlugin(bitDocs)`
+ * 
+ * @param {Object} bitDocs Configuration object with a `register` method.
  * 
  * @body
  * 
- * This plugin registers onto these hooks:
+ * ## Use
+ * 
+ * Registers onto these hooks:
  *   - `tags`
  *   - `processor`
  *   - `html`
  * 
- * Registering the `tag` hook adds JavaScript-related tags:
- *   - [bit-docs-js/tags/function @function]
+ * ### Tags
+ * 
+ * Registering the `tags` hook adds JavaScript-related tags:
+ *   - [bit-docs-js/tag/function]
+ *   - [bit-docs-js/tags/module @module]
+ *   - [bit-docs-js/tags/option @option]
  *   - [bit-docs-js/tags/param @param]
+ *   - [bit-docs-js/tags/property @property]
+ *   - [bit-docs-js/tags/prototype @prototype]
+ *   - [bit-docs-js/tags/return @return]
  *   - [bit-docs-js/tags/signature @signature]
- *   - ...
+ *   - [bit-docs-js/tags/typedef @typedef]
+ * 
+ * ### Processor
  * 
  * Registering the `processor` hook adds a processor for `*.js` files that gets
  * code comments in JavaScript, and processes tags like `@function` and
- * `@param` into docObjects that are subsequently added to the docMap.
+ * `@param` into [bit-docs/types/docObject]s that are subsequently added to the
+ * [bit-docs/types/docMap].
  *
- * The processor is also smart enough process regular comments above functions
- * that have not explicitly been documented with closure type annotations, and
- * extracts basic signature information such as parameters and/or return type.
+ * Comments above functions that do not include [bit-docs-js/types/tag]s
+ * will still be processed as [bit-docs-js/types/tagBlock]s as the processor
+ * extracts basic signature information such as parameters and/or return type
+ * from the [bit-docs-js/types/codeLine].
+ * 
+ * ### HTML
  * 
  * Registering the `html` hook adds a mustache template used to generate the
  * HTML for the tags added by this plugin.
@@ -44,5 +60,4 @@ module.exports = function(bitDocs){
     bitDocs.register("html", {
         templates: path.join(__dirname, "templates")
     });
-
 };

process/code.js

@@ -1,33 +1,32 @@
 var _ = require("lodash");
+
 /**
- * @function documentjs.process.code
- * @parent documentjs.process.methods
- *
- * Process a code hint into properties on a `docObject`.
- *
- * @signature `documentjs.process.code(options, callback)`
+ * @parent bit-docs-js/modules
+ * @module {function} bit-docs-js/process/code
  *
- * Using the `options.code`, and `options.tags`, processes the code
- * into properties on a docObject.  The `callback` is called with the new docObject.
+ * Process a line of code to add properties on a [bit-docs/types/docObject].
  *
- * @param {documentjs.process.processOptions} options An options object that contains
- * the code to process.
+ * @signature `processCode(options, callback)`
  *
- * @param {function(documentjs.process.docObject,documentjs.process.docObject)} callback(newDoc,newScope)
+ * @param {bit-docs-js/types/processCodeOptions} options
+ * 
+ * Options object that includes the [bit-docs-process-tags/types/tagBlock] and
+ * any line of code that immediately followed the block.
+ * 
+ * @param {bit-docs/types/processorCallback} callback
  *
- * A function that is called back with a docObject created from the code and the scope
- * `docObject`.  If
- * no docObject is created, `newDoc` will be null.
+ * Callback to call with the new [bit-docs/types/docObject].
  *
  * @body
  *
  * ## Use
  *
- *     documentjs.process.code(
- * 	      {code: "foo: function(){"},
- *        function(newDoc){
- *          newDoc.type //-> "function"
- *        }
+ *     processCode({
+ *         code: "foo: function(){"
+ *       },
+ *       function(newDoc) {
+ *         newDoc.type //-> "function"
+ *       }
  *     )
  */
 module.exports = function(options, callback){

process/code_and_comment.js

@@ -1,33 +1,35 @@
-var processCode = require("./code"),
-	processTags = require("bit-docs-process-tags");
+var processCode = require("./code");
+var processTags = require("bit-docs-process-tags");
 
 var typeCheckReg = /^\s*@(\w+)/;
+
 /**
- * @function documentjs.process.codeAndComment
- * @parent documentjs.process.methods
- *
- * @signature `documentjs.process.codeAndComment(options, callback)`
+ * @parent bit-docs-js/modules
+ * @module {function} bit-docs-js/process/codeAndComment
  *
- * Processes a code suggestion and then a comment and produces a docObject.
+ * @signature `processCodeAndComment(options, callback)`
  *
- * @param {documentjs.process.processOptions} options An options object that contains
- * the code and comment to process.
+ * Processes a [bit-docs-js/types/codeTagBlock] and the
+ * [bit-docs-js/types/codeLine] immediately following the
+ * [bit-docs-js/types/codeTagBlock] to produce a new
+ * [bit-docs/types/docObject].
  *
- * @param {function(documentjs.process.docObject,documentjs.process.docObject)} callback(newDoc,newScope)
+ * @param {bit-docs-js/types/processCodeOptions} options
+ * 
+ * Options object that includes the [bit-docs-js/types/codeTagBlock] and any
+ * [bit-docs-js/types/codeLine] that immediately followed the
+ * [bit-docs-js/types/codeTagBlock].
  *
- * A function that is called back with a docObject created from the code and the scope
- * `docObject`.  If
- * no docObject is created, `newDoc` will be null.
+ * @param {bit-docs/types/processorCallback} callback
  *
- * @option newDoc the new documentation object
- * @option newScope the new scope
+ * Callback to call with the new [bit-docs/types/docObject].
  */
 module.exports = function(options, callback){
-	var self = this,
-		comment = options.comment;
+	var self = this;
+	var comment = options.comment;
 
-	var firstLine = (typeof comment == 'string' ? comment : comment[0]) || "",
-		check = firstLine.match(typeCheckReg);
+	var firstLine = (typeof comment == 'string' ? comment : comment[0]) || "";
+	var check = firstLine.match(typeCheckReg);
 
 	if(check){
 		if(!options.docObject){

tags/class.js

@@ -1,29 +1,55 @@
-var getParent = require("bit-docs-process-tags/get-parent"),
-	tnd = require("bit-docs-type-annotate").typeNameDescription;
+var getParent = require("bit-docs-process-tags/get-parent");
+var tnd = require("bit-docs-type-annotate").typeNameDescription;
 
-	var funcMatch = /(?:([\w\.\$]+)|(["'][^"']+["']))\s*[=]\s*function\s?\(([^\)]*)/,
-		codeMatch = /([\w\.\$]+?).extend\(\s*["']([^"']*)["']/;
+var funcMatch = /(?:([\w\.\$]+)|(["'][^"']+["']))\s*[=]\s*function\s?\(([^\)]*)/;
+var codeMatch = /([\w\.\$]+?).extend\(\s*["']([^"']*)["']/;
 
+/**
+ * @parent bit-docs-js/modules
+ * @module {bit-docs-process-tags/types/tag} bit-docs-js/tags/class
+ * 
+ * @description Deprecated. Use [bit-docs-js/tags/constructor] instead.
+ * 
+ * @signature `require('./tags/class');`
+ * 
+ * @return {bit-docs-process-tags/types/tag} Tag object configured for the
+ * [bit-docs-js/tag/class] tag.
+ * 
+ * @body
+ * 
+ * Gets converted to [bit-docs-js/tags/constructor].
+ */
+module.exports = {
 	/**
-	 * @constructor documentjs.tags.constructor @constructor
-	 * @hide
-	 * Document a constructor function.
-	 *
-	 * @signature `@constructor NAME [TITLE]`
-	 * @parent documentjs.tags
+	 * @signature `add(line)`
+	 * 
+	 * [bit-docs-process-tags/types/tag.add] for [bit-docs-js/tag/class].
+	 * 
+	 * Simply converts the scope into that of [bit-docs-js/tags/constructor].
+	 * 
+	 * @param {String} line Text from [bit-docs-js/tag/class] until the end
+	 * of line.
+	 * 
+	 * For example:
+	 * 
+	 * @codestart javascript
+	 * @@class my-project/lib/index
+	 * @codeend
+	 * 
+	 * @return {bit-docs-process-tags/types/processTagsCommand} `['scope', this]`
 	 */
-	module.exports = {
-		add: function(line, curData, scope, docMap){
-			console.warn("Using the @class directive.  It is deprecated!");
-			// it's possible this has already been matched as something else ... clear parent
+	add: function(line){
+		console.warn("Using the @class directive.  It is deprecated!");
+		// it's possible this has already been matched as something else
+		// ... clear parent
 
-			this.type = "constructor";
-			var data = tnd(line);
-			if(data.name) {
-				this.name = data.name;
-			}
-
-			this.title = data.description;
-			return ["scope",this];
+		this.type = "constructor";
+		var data = tnd(line);
+		if(data.name) {
+			this.name = data.name;
 		}
-	};
+
+		this.title = data.description;
+		return ["scope",this];
+	}
+};

tags/class.md

@@ -0,0 +1,10 @@
+@parent bit-docs-js/tags
+@constructor bit-docs-js/tag/class @class
+
+@description Deprecated tag. Use [bit-docs-js/tag/constructor] instead.
+
+@signature `@class NAME [TITLE]`
+
+@body
+
+Gets converted to [bit-docs-js/tag/constructor].