Merge branch 'docs/jsdoc/improve-type-information' of github.com:EB-F…

…orks/ejs

docs/jsdoc/callbacks.jsdoc

@@ -3,7 +3,7 @@
  *
  * @callback RenderFileCallback
  * @param {?Error}  err error, if any resulted from the rendering process
- * @param {?String} str output string, is `null` if there is an error
+ * @param {?String} [str] output string, is `null` or `undefined` if there is an error
  * @static
  * @global
  */

docs/jsdoc/template-functions.jsdoc

@@ -58,7 +58,8 @@
  * @param {Error}  err      Error object
  * @param {String} str      full EJS source
  * @param {String} filename file name of the EJS file
- * @param {String} lineno   line number of the error
+ * @param {Number} lineno   line number of the error
+ * @param {EscapeCallback} esc
  * @static
  * @global
  */

lib/ejs.js

@@ -49,6 +49,7 @@ var path = require('path');
 var utils = require('./utils');
 
 var scopeOptionWarned = false;
+/** @type {string} */
 var _VERSION_STRING = require('../package.json').version;
 var _DEFAULT_OPEN_DELIMITER = '<';
 var _DEFAULT_CLOSE_DELIMITER = '>';
@@ -99,7 +100,7 @@ exports.localsName = _DEFAULT_LOCALS_NAME;
  * Promise implementation -- defaults to the native implementation if available
  * This is mostly just for testability
  *
- * @type {Function}
+ * @type {PromiseConstructorLike}
  * @public
  */
 
@@ -111,7 +112,7 @@ exports.promiseImpl = (new Function('return this;'))().Promise;
  *
  * @param {String}  name     specified path
  * @param {String}  filename parent file path
- * @param {Boolean} isDir    parent file path whether is directory
+ * @param {Boolean} [isDir=false] whether the parent file path is a directory
  * @return {String}
  */
 exports.resolveInclude = function(name, filename, isDir) {
@@ -296,20 +297,21 @@ function includeFile(path, options) {
  * Re-throw the given `err` in context to the `str` of ejs, `filename`, and
  * `lineno`.
  *
- * @implements RethrowCallback
+ * @implements {RethrowCallback}
  * @memberof module:ejs-internal
  * @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
+ * @param {String} flnm     file name of the EJS file
+ * @param {Number} lineno   line number of the error
+ * @param {EscapeCallback} esc
  * @static
  */
 
-function rethrow(err, str, flnm, lineno, esc){
+function rethrow(err, str, flnm, lineno, esc) {
   var lines = str.split('\n');
   var start = Math.max(lineno - 3, 0);
   var end = Math.min(lines.length, lineno + 3);
-  var filename = esc(flnm); // eslint-disable-line
+  var filename = esc(flnm);
   // Error context
   var context = lines.slice(start, end).map(function (line, i){
     var curr = i + start + 1;
@@ -338,7 +340,7 @@ function stripSemi(str){
  *
  * @param {String}  template EJS template
  *
- * @param {Options} opts     compilation options
+ * @param {Options} [opts] compilation options
  *
  * @return {(TemplateFunction|ClientFunction)}
  * Depending on the value of `opts.client`, either type might be returned.
@@ -478,6 +480,7 @@ function Template(text, opts) {
   opts = opts || {};
   var options = {};
   this.templateText = text;
+  /** @type {string | null} */
   this.mode = null;
   this.truncate = false;
   this.currentLine = 1;
@@ -535,12 +538,16 @@ Template.prototype = {
   },
 
   compile: function () {
+    /** @type {string} */
     var src;
+    /** @type {ClientFunction} */
     var fn;
     var opts = this.opts;
     var prepended = '';
     var appended = '';
+    /** @type {EscapeCallback} */
     var escapeFn = opts.escapeFunction;
+    /** @type {FunctionConstructor} */
     var ctor;
 
     if (!this.source) {

lib/utils.js

@@ -146,7 +146,7 @@ exports.shallowCopyFromList = function (to, from, list) {
  * Simple in-process cache implementation. Does not implement limits of any
  * sort.
  *
- * @implements Cache
+ * @implements {Cache}
  * @static
  * @private
  */