Code coverage report for index.js

Statements: 100% (36 / 36)      Branches: 90% (27 / 30)      Functions: 100% (9 / 9)      Lines: 100% (36 / 36)      Ignored: none     

All files » __root__/ » index.js
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183    25                                                     25 64 64 159 1431 1277     159                         25 74 74                                                     25 64 64   64 2     64   64 64 2   62 62             104                               1                                               25 5   5 2     5   5 5 2   3         3                               25   25          
'use strict';
 
var sort = require('./lib/sort'),
  nest = require('./lib/nest'),
  filterAccess = require('./lib/filter_access'),
  filterJS = require('./lib/filter_js'),
  dependency = require('./lib/input/dependency'),
  shallow = require('./lib/input/shallow'),
  parseJavaScript = require('./lib/parsers/javascript'),
  polyglot = require('./lib/parsers/polyglot'),
  github = require('./lib/github'),
  hierarchy = require('./lib/hierarchy'),
  inferName = require('./lib/infer/name'),
  inferKind = require('./lib/infer/kind'),
  inferAugments = require('./lib/infer/augments'),
  inferParams = require('./lib/infer/params'),
  inferProperties = require('./lib/infer/properties'),
  inferMembership = require('./lib/infer/membership'),
  inferReturn = require('./lib/infer/return'),
  formatLint = require('./lib/lint').formatLint,
  lintComments = require('./lib/lint').lintComments;
 
/**
 * Build a pipeline of comment handlers.
 * @param {...Function|null} args - Pipeline elements. Each is a function that accepts
 *  a comment and can return a comment or undefined (to drop that comment).
 * @returns {Function} pipeline
 * @private
 */
function pipeline() {
  var elements = arguments;
  return function (comment) {
    for (var i = 0; comment && i < elements.length; i++) {
      if (elements[i]) {
        comment = elements[i](comment);
      }
    }
    return comment;
  };
}
 
/**
 * Given an array of indexes and options for whether to resolve shallow
 * or deep dependencies, resolve dependencies.
 *
 * @param {Array<string>|string} indexes files to process
 * @param {Object} options options
 * @param {Function} callback called with results
 * @returns {undefined}
 */
function expandInputs(indexes, options, callback) {
  var inputFn = (options.polyglot || options.shallow) ? shallow : dependency;
  inputFn(indexes, options, callback);
}
 
/**
 * Generate JavaScript documentation as a list of parsed JSDoc
 * comments, given a root file as a path.
 *
 * @name documentation
 * @param {Array<string>|string} indexes files to process
 * @param {Object} options options
 * @param {Array<string>} options.external a string regex / glob match pattern
 * that defines what external modules will be whitelisted and included in the
 * generated documentation.
 * @param {boolean} [options.polyglot=false] parse comments with a regex rather than
 * a proper parser. This enables support of non-JavaScript languages but
 * reduces documentation's ability to infer structure of code.
 * @param {boolean} [options.shallow=false] whether to avoid dependency parsing
 * even in JavaScript code. With the polyglot option set, this has no effect.
 * @param {Array<string|Object>} [options.order=[]] optional array that
 * defines sorting order of documentation
 * @param {Object} [options.hljs] hljs optional options
 * @param {boolean} [options.hljs.highlightAuto=false] hljs automatically detect language
 * @param {Array} [options.hljs.languages] languages for hljs to choose from
 * @param {Function} callback to be called when the documentation generation
 * is complete, with (err, result) argumentsj
 * @returns {undefined} calls callback
 */
module.exports = function (indexes, options, callback) {
  options = options || {};
  options.hljs = options.hljs || {};
 
  if (typeof indexes === 'string') {
    indexes = [indexes];
  }
 
  var parseFn = (options.polyglot) ? polyglot : parseJavaScript;
 
  return expandInputs(indexes, options, function (error, inputs) {
    if (error) {
      return callback(error);
    }
    try {
      callback(null,
        filterAccess(
          options.private ? [] : undefined,
          hierarchy(
            inputs
              .filter(filterJS(options.extension))
              .reduce(function (memo, file) {
                return memo.concat(parseFn(file));
              }, [])
              .map(pipeline(
                inferName(),
                inferAugments(),
                inferKind(),
                inferParams(),
                inferProperties(),
                inferReturn(),
                inferMembership(),
                nest,
                options.github && github
              ))
              .filter(Boolean)
              .sort(sort.bind(undefined, options.order)))));
    } catch (e) {
      callback(e);
    }
  });
};
 
/**
 * Lint files for non-standard or incorrect documentation
 * information, returning a potentially-empty string
 * of lint information intended for human-readable output.
 *
 * @param {Array<string>|string} indexes files to process
 * @param {Object} options options
 * @param {Array<string>} options.external a string regex / glob match pattern
 * that defines what external modules will be whitelisted and included in the
 * generated documentation.
 * @param {boolean} [options.polyglot=false] parse comments with a regex rather than
 * a proper parser. This enables support of non-JavaScript languages but
 * reduces documentation's ability to infer structure of code.
 * @param {boolean} [options.shallow=false] whether to avoid dependency parsing
 * even in JavaScript code. With the polyglot option set, this has no effect.
 * @param {Function} callback to be called when the documentation generation
 * is complete, with (err, result) argumentsj
 * @returns {undefined} calls callback
 */
module.exports.lint = function lint(indexes, options, callback) {
  options = options || {};
 
  if (typeof indexes === 'string') {
    indexes = [indexes];
  }
 
  var parseFn = (options.polyglot) ? polyglot : parseJavaScript;
 
  return expandInputs(indexes, options, function (error, inputs) {
    if (error) {
      return callback(error);
    }
    callback(null,
      formatLint(hierarchy(
        inputs
          .filter(filterJS(options.extension))
          .reduce(function (memo, file) {
            return memo.concat(parseFn(file));
          }, [])
          .map(pipeline(
            lintComments,
            inferName(),
            inferAugments(),
            inferKind(),
            inferParams(),
            inferProperties(),
            inferReturn(),
            inferMembership(),
            nest))
          .filter(Boolean))));
  });
};
 
module.exports.expandInputs = expandInputs;
 
module.exports.formats = {
  html: require('./lib/output/html'),
  md: require('./lib/output/markdown'),
  json: require('./lib/output/json')
};