next

- Added at NextDoor
- Version 2.0 of this modules' docs.

Author: leoj3n

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,26 +3,29 @@ var processJavaScript = require("./process/javascript");
 var path = require("path");
 
 /**
- * @parent plugins
- * @module {function} bit-docs-js
- * @group bit-docs-js/modules modules
- * @group bit-docs-js/tags tags
- * @group bit-docs-js/templates templates
+ * @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`
  * 
+ * ### Tags
+ * 
  * Registering the `tags` hook adds JavaScript-related tags:
- *   - [bit-docs-js/tags/function @function]
+ *   - [bit-docs-js/tag/function]
  *   - [bit-docs-js/tags/module @module]
  *   - [bit-docs-js/tags/option @option]
  *   - [bit-docs-js/tags/param @param]
@@ -32,14 +35,19 @@ var path = require("path");
  *   - [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 [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.

process/code.js

@@ -4,33 +4,29 @@ var _ = require("lodash");
  * @parent bit-docs-js/modules
  * @module {function} bit-docs-js/process/code
  *
- * Process a code hint into properties on a [bit-docs/types/docObject].
+ * Process a line of code to add properties on a [bit-docs/types/docObject].
  *
  * @signature `processCode(options, callback)`
  *
- * Using the `options.code`, and `options.tags`, processes the code into
- * properties on a [bit-docs/types/docObject].
+ * @param {bit-docs-js/types/processCodeOptions} options
  * 
- * The `callback` is called with the new [bit-docs/types/docObject].
- *
- * @param {bit-docs/types/processOptions} options An options object that
- * contains the code to process.
- *
- * @param {function(bit-docs/types/docObject,bit-docs/types/docObject)} callback(newDoc,newScope)
+ * 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 [bit-docs/types/docObject] created
- * from the code and the scope `docObject`. If no [bit-docs/types/docObject] is
- * created, `newDoc` will be null.
+ * Callback to call with the new [bit-docs/types/docObject].
  *
  * @body
  *
  * ## Use
  *
- *     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

@@ -9,20 +9,20 @@ var typeCheckReg = /^\s*@(\w+)/;
  *
  * @signature `processCodeAndComment(options, callback)`
  *
- * Processes a code suggestion and then a comment and produces a
+ * 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 {bit-docs/types/processOptions} options An options object that
- * contains the code and comment to process.
+ * @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].
  *
- * @param {function(bit-docs/types/docObject,bit-docs/types/docObject)} callback(newDoc,newScope)
+ * @param {bit-docs/types/processorCallback} callback
  *
- * A function that is called back with a [bit-docs/types/docObject] created
- * from the code and the scope `docObject`. If no [bit-docs/types/docObject] is
- * created, `newDoc` will be null.
- *
- * @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;

tags/class.js

@@ -5,16 +5,40 @@ var funcMatch = /(?:([\w\.\$]+)|(["'][^"']+["']))\s*[=]\s*function\s?\(([^\)]*)/
 var codeMatch = /([\w\.\$]+?).extend\(\s*["']([^"']*)["']/;
 
 /**
- * @parent bit-docs-js/tags
- * @module {bit-docs-process-tags/tag} bit-docs-js/tags/class @class
- * @hide
+ * @parent bit-docs-js/modules
+ * @module {bit-docs-process-tags/types/tag} bit-docs-js/tags/class
  * 
- * DEPRECATED: Gets converted to [bit-docs-js/tags/constructor].
- *
- * @signature `@class NAME [TITLE]`
+ * @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 = {
-	add: function(line, curData, scope, docMap){
+	/**
+	 * @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]`
+	 */
+	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

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].

tags/codeend.js

@@ -1,67 +1,83 @@
+/**
+ * @parent bit-docs-js/modules
+ * @module {bit-docs-process-tags/types/tag} bit-docs-js/tags/codeend
+ * 
+ * @description Use this module to add the [bit-docs-js/tag/codeend] tag.
+ * 
+ * @signature `require('./tags/codeend');`
+ * 
+ * @return {bit-docs-process-tags/types/tag} Tag object configured for the
+ * [bit-docs-js/tag/codeend] tag.
+ * 
+ * @body
+ */
+module.exports =  {
 	/**
-	 * @hide
-	 * @parent bit-docs-js/tags
-	 * @module {bit-docs/types/tag} bit-docs-js/tags/codeend @codeend
+	 * @signature `add(line, data)`
 	 * 
-	 * @description 
+	 * [bit-docs-process-tags/types/tag.add] for [bit-docs-js/tag/codeend].
 	 * 
-	 * Stops a code block.
+	 * @param {String} line Text from [bit-docs-js/tag/codeend] until the end
+	 * of line.
 	 * 
-	 * ### Example:
+	 * For example:
 	 * 
-	 * @codestart
-	 *
-	 *  /* 
-	 *   * @codestart
-	 *   *  /* @class
-	 *   *   * Person represents a human with a name.  Read about the 
-	 *   *   * animal class [Animal | here].
-	 *   *   * @constructor
-	 *   *   * You must pass in a name.
-	 *   *   * @param {String} name A person's name
-	 *   *   *|
-	 *   *   Person = function(name){
-	 *   *      this.name = name
-	 *   *      Person.count ++;
-	 *   *   }
-	 *   *  /* @Static *|
-	 *   *  steal.Object.extend(Person, {
-	 *   *      /* Number of People *|
-	 *   *      count: 0
-	 *   *  })
-	 *   *  /* @Prototype *|
-	 *   *  Person.prototype = {
-	 *   *     /* Returns a formal name 
-	 *   *      * @return {String} the name with "Mrs." added
-	 *   *      *|
-	 *   *      fancyName : function(){
-	 *   *         return "Mrs. "+this.name;
-	 *   *      }
-	 *   *  }
-	 *   * @codeend
-	 *   *|
-	 *
-	 * @codeend 
+	 * @codestart javascript
+	 * @@codeend
+	 * @codeend
+	 * 
+	 * @param {Object} curData Custom data object hydrated by [bit-docs-js/tags/codestart].
+	 * 
+	 * For example:
+	 * 
+	 * ```js
+	 * {
+	 *     type: 'javascript',
+	 *     lines: ['/**', ' * @demo demos/example.html 300', ' *|'],
+	 *     last: {
+	 *         code: '@demo PATH [HEIGHT]',
+	 *         description: '\n',
+	 *         params: []
+	 *     },
+	 *     _last: undefined
+	 * }
+	 * ```
+	 * 
+	 * @return {bit-docs-process-tags/types/processTagsCommand} `['poppop', '...']`.
+	 * 
+	 * For example:
+	 * 
+	 * @codestart javascript
+	 * [
+	 *   'poppop',
+	 *   '```javascript\n/**\n * @demo demos/example.html 300\n *|\n```'
+	 * ]
+	 * @codeend
 	 */
-	module.exports =  {
-		add: function( line, data ) {
+	add: function( line, data ) {
+		if (!data.lines ) {
+			console.warn('you probably have a @codeend without a @codestart')
+		}
 
-			if (!data.lines ) {
-				console.warn('you probably have a @codeend without a @codestart')
-			}
+		var joined = data.lines.join("\n");
 
-			var joined = data.lines.join("\n");
+		if ( data.type == "javascript" || data.type == "js") { //convert comments
+			joined = joined.replace(/\*\|/g, "*/")
+		}
 
-			if ( data.type == "javascript" || data.type == "js") { //convert comments
-				joined = joined.replace(/\*\|/g, "*/")
-			}
-			var out = "```" + data.type + "\n"
-				+ joined.replace(/&lt;/g,"<")
-						.replace(/&gt;/g,">")
-						.replace(/&amp;/g,"&") +
+		var out = "```" + data.type + "\n"
+			+ joined.replace(/&lt;/g,"<")
+					.replace(/&gt;/g,">")
+					.replace(/&amp;/g,"&") +
 			"\n```";
 
-			return ["poppop", out];
-		},
-		keepStack: true
-	};
+		return ["poppop", out];
+	},
+	/**
+	 * @property {Boolean} keepStack
+	 * 
+	 * [bit-docs-process-tags/types/tag.keepStack] set `true` for
+	 * [bit-docs-js/tag/codeend].
+	 */
+	keepStack: true
+};