documentation/lib/parse.js

'use strict';

var doctrine = require('doctrine'),
  error = require('./error'),
  flatten = require('./flatten'),
  normalize = require('./normalize');

/**
 * Parse a comment with doctrine, decorate the result with file position and code
 * context, handle parsing errors, and fix up various infelicities in the structure
 * outputted by doctrine.
 *
 * @param {string} comment - input to be parsed
 * @param {Object} loc - location of the input
 * @param {Object} context - code context of the input
 * @return {Object} an object conforming to the
 * [documentation JSON API](https://github.com/documentationjs/api-json) schema
 */
module.exports = function (comment, loc, context) {
  var result = doctrine.parse(comment, {
    // have doctrine itself remove the comment asterisks from content
    unwrap: true,
    // enable parsing of optional parameters in brackets, JSDoc3 style
    sloppy: true,
    // `recoverable: true` is the only way to get error information out
    recoverable: true,
    // include line numbers
    lineNumbers: true
  });

  result.loc = loc;
  result.context = context;

  var i = 0;
  var errors = [];
  while (i < result.tags.length) {
    var tag = result.tags[i];
    if (tag.errors) {
      for (var j = 0; j < tag.errors.length; j++) {
        errors.push(error(tag, result, tag.errors[j]));
      }
      result.tags.splice(i, 1);
    } else {
      i++;
    }
  }

  result = flatten(normalize(result));

  if (errors.length) {
    result.errors = errors;
  }

  return result;
};