Move some parts of the documentaton to docs/types.jsdoc

[ci skip]

docs/types.jsdoc

@@ -0,0 +1,109 @@
+/**
+ * Compilation and rendering options.
+ *
+ * @typedef Options
+ * @type {Object}
+ *
+ * @property {Boolean} [debug=false]
+ * Log generated JavaScript source for the EJS template to the console.
+ *
+ * @property {Boolean} [compileDebug=true]
+ * Include additional runtime debugging information in generated template
+ * functions.
+ *
+ * @property {Boolean} [_with=true]
+ * Whether or not to use `with () {}` construct in the generated template
+ * functions. If set to `false`, data is still accessible through the object
+ * whose name is specified by {@link module:ejs.localsName} (default to
+ * `locals`).
+ *
+ * @property {Boolean} [client=false]
+ * Whether or not to compile functions that are to be included in the browser.
+ *
+ * @property {EscapeCallback} [escape={@link module:utils.escapeXML}]
+ * The escaping function used with `<%=` construct. It is used in rendering
+ * and is `.toString()`ed in the generation of client functions.
+ *
+ * @property {String}  [filename='undefined']
+ * The filename of the template. Used in inclusion, caching, and error
+ * reporting.
+ * @property {String}  [delimiter='%']
+ * The delimiter used in template compilation.
+ *
+ * @property {Boolean} [cache=false]
+ * Whether or not to enable caching of template functions. Beware that
+ * the options of compilation are not checked as being the same, so
+ * special handling is required if, for example, you want to cache client
+ * and regular functions of the same file.
+ *
+ * Requires `filename` to be set. Only works with rendering function.
+ *
+ * @property {Object}  [context=this]
+ * The Object to which `this` is set during rendering.
+ *
+ * @property {Object}  [scope=this]
+ * Alias of `context`. Deprecated.
+ *
+ * @static
+ * @global
+ */
+
+/**
+ * This type of function is returned from {@link module:ejs.compile}, when
+ * {@link Options}`.client` is false.
+ *
+ * @callback TemplateFunction
+ * @param {Object}          [locals={}]
+ * an object of data to be passed into the template.
+ * @static
+ * @global
+ */
+
+/**
+ * This type of function is returned from {@link module:ejs.compile}, when
+ * {@link Options}`.client` is true.
+ *
+ * This is also used internally to generate a
+ * {@link TemplateFunction}.
+ *
+ * @callback ClientFunction
+ * @param {Object}          [locals={}]
+ * an object of data to be passed into the template. The name of this variable
+ * is adjustable through {@link module:ejs.localsName}.
+ *
+ * @param {EscapeCallback}  [escape={@link Options}.escape]
+ * callback used to escape variables
+ *
+ * @param {IncludeCallback} [include]
+ * callback used to include files at runtime with `include()`
+ *
+ * @param {RethrowCallback} [rethrow={@link module:ejs-internal.rethrow}]
+ * callback used to handle and rethrow errors
+ *
+ * @static
+ * @global
+ */
+
+/**
+ * This type of callback is used when {@link Options}`.compileDebug`
+ * is true, and an error in the template is thrown. By default it is used to
+ * throw an error in a better-formatted way.
+ *
+ * @callback RethrowCallback
+ * @param {Error}  err      Error object
+ * @param {String} str      EJS source
+ * @param {String} filename file name of the EJS file
+ * @param {String} lineno   line number of the error
+ * @static
+ * @global
+ */
+
+/**
+ * This type of callback is used when `<%=` construct is used.
+ *
+ * @callback EscapeCallback
+ * @param  {String} markup Input string
+ * @return {String}        Escaped string
+ * @static
+ * @global
+ */

lib/ejs.js

@@ -195,8 +195,7 @@ function includeSource(path, options) {
  * Re-throw the given `err` in context to the `str` of ejs, `filename`, and
  * `lineno`.
  *
- * This implements {@link RethrowCallback}.
- *
+ * @implements RethrowCallback
  * @memberof module:ejs-internal
  * @param {Error}  err      Error object
  * @param {String} str      EJS source
@@ -249,104 +248,6 @@ function cpOptsInData(data, opts) {
   });
 }
 
-/**
- * Compilation and rendering options.
- *
- * @typedef Options
- * @type {Object}
- *
- * @property {Boolean} [debug=false]
- * Log generated JavaScript source for the EJS template to the console.
- *
- * @property {Boolean} [compileDebug=true]
- * Include additional runtime debugging information in generated template
- * functions.
- *
- * @property {Boolean} [_with=true]
- * Whether or not to use `with () {}` construct in the generated template
- * functions. If set to `false`, data is still accessible through the `locals`
- * object.
- *
- * @property {Boolean} [localsName='locals']
- * The name of the object containing the locals. Especially useful when
- * `_with` is `false`. Overrides
- *
- * @property {Boolean} [client=false]
- * Whether or not to compile functions that are to be included in the browser.
- *
- * @property {String}  [filename='undefined']
- * The filename of the template. Used in inclusion, caching, and error
- * reporting.
- * @property {String}  [delimiter='%']
- * The delimiter used in template compilation.
- *
- * @property {Boolean} [cache=false]
- * Whether or not to enable caching of template functions. Beware that
- * the options of compilation are not checked as being the same, so
- * special handling is required if, for example, you want to cache client
- * and regular functions of the same file.
- *
- * Requires `filename` to be set. Only works with rendering function.
- *
- * @property {Object}  [context=this]
- * The Object to which `this` is set during rendering.
- *
- * @property {Object}  [scope=this]
- * Alias of `context`. Deprecated.
- *
- * @static
- * @global
- */
-
-/**
- * This type of function is returned from {@link module:ejs.compile}, when
- * {@link Options}`.client` is false.
- *
- * @callback TemplateFunction
- * @param {Object}          [locals={}]
- * an object of data to be passed into the template.
- * @static
- * @global
- */
-
-/**
- * This type of function is returned from {@link module:ejs.compile}, when
- * {@link Options}`.client` is true.
- *
- * This is also used internally to generate a
- * {@link TemplateFunction}.
- *
- * @callback ClientFunction
- * @param {Object}          [locals={}]
- * an object of data to be passed into the template.
- *
- * @param {EscapeFunction}  [escape={@link module:utils.escapeXML}]
- * callback used to escape variables
- *
- * @param {IncludeFunction} [include]
- * callback used to include files at runtime with `include()`
- *
- * @param {RethrowCallback} [rethrow={@link module:ejs-internal.rethrow}]
- * callback used to handle and rethrow errors
- *
- * @static
- * @global
- */
-
-/**
- * This type of callback is used when {@link Options}`.compileDebug`
- * is true, and an error in the template is thrown. By default it is used to
- * throw an error in a better-formatted way.
- *
- * @callback RethrowCallback
- * @param {Error}  err      Error object
- * @param {String} str      EJS source
- * @param {String} filename file name of the EJS file
- * @param {String} lineno   line number of the error
- * @static
- * @global
- */
-
 /**
  * Compile the given `str` of ejs into a template function.
  *

package.json

@@ -36,7 +36,7 @@
   "scripts": {
     "test": "mocha",
     "coverage": "istanbul cover node_modules/mocha/bin/_mocha",
-    "doc": "rimraf out && jsdoc -c jsdoc.json lib/*",
-    "devdoc": "rimraf out && jsdoc -p -c jsdoc.json lib/*"
+    "doc": "rimraf out && jsdoc -c jsdoc.json lib/* docs/*.jsdoc",
+    "devdoc": "rimraf out && jsdoc -p -c jsdoc.json lib/* docs/*.jsdoc"
   }
 }