How to use doctrine - 10 common examples

/* eslint-env mocha */
'use strict'

const Syntax = require('doctrine').Syntax
const expect = require('chai').expect
const remark = require('remark')

const Utils = require('../lib/utils')

describe('utils', () => {
  const u = new Utils({hljs: {highlightAuto: false}}, [])

  describe('md', () => {
    it('renders remark asts', () => {
      expect(
        u.md(
          remark().parse(
            'Converts from `Result` to `?Error`'
          )
        )

"name": "type",
        "value": "type",
        "string": "this.type"
      },
      "value": "this.type = type;\r",
      "line": 44,
      "loc": { "start": { "line": 44, "column": 1424 }, "end": { "line": 44, "column": 1442 } }
    }
  },
*/

    for (var i = 0; i < blocks.length; i++)
    {
        var block = blocks[i];

        comments.push(doctrine.parse(block.value, doctrineOptions));
    }

    // comments = JSON.stringify(comments);
    comments = beautify(comments, null, 2, 100); // just for debugging really
    // comments = beautify(blocks, null, 2, 100); // just for debugging really

    fs.writeFile(dest, comments, { encoding: 'utf8', flag: 'w' }, function (error) {

        if (error)
        {
            throw error;
        }
        else
        {
            console.log('Comments written');
        }

return comments.filter(comment => {
    if (isCommentBlock(comment) && /^\*/.test(comment.value)) {
      const jsdoc = doctrine.parse(`/* ${comment.value}*/`, { unwrap: true });
      return (
        jsdoc.tags.some(tag => tag.title === "typedef") &&
        !jsdoc.tags.some(tag => tag.title === "private")
      );
    }
    return false;
  });
};

const summary = (summaryTag && summaryTag.description) || '';
    const description = docs.description;

    let functionReturn = getReturnFromAnnotation(docs);
    if (functionReturn === undefined && babel.isFunction(node)) {
      functionReturn = inferReturnFromBody(node);
    }

    // TODO(justinfagnani): consolidate with similar param processing code in
    // docs.ts
    const functionParams: {type: string, desc: string, name: string}[] = [];
    const templateTypes: string[] = [];
    for (const tag of docs.tags) {
      if (tag.title === 'param') {
        functionParams.push({
          type: tag.type ? doctrine.type.stringify(tag.type) : 'N/A',
          desc: tag.description || '',
          name: tag.name || 'N/A'
        });
      } else if (tag.title === 'template') {
        for (let t of (tag.description || '').split(',')) {
          t = t.trim();
          if (t.length > 0) {
            templateTypes.push(t);
          }
        }
      }
    }
    // TODO(fks): parse params directly from `fn`, merge with docs.tags data

    const specificName = functionName.slice(functionName.lastIndexOf('.') + 1);
    this.functions.add(new ScannedFunction(

function generateDescription(required, description, type) {
  let deprecated = '';

  if (type.name === 'custom') {
    const deprecatedInfo = getDeprecatedInfo(type);

    if (deprecatedInfo) {
      deprecated = `*Deprecated*. ${deprecatedInfo.explanation}<br><br>`;
    }
  }

  const parsed = parseDoctrine(description);

  // two new lines result in a newline in the table. all other new lines
  // must be eliminated to prevent markdown mayhem.
  const jsDocText = parsed.description.replace(/\n\n/g, '<br>').replace(/\n/g, ' ');

  if (parsed.tags.some((tag) =&gt; tag.title === 'ignore')) return null;
  let signature = '';

  if (type.name === 'func' &amp;&amp; parsed.tags.length &gt; 0) {
    // Remove new lines from tag descriptions to avoid markdown errors.
    parsed.tags.forEach((tag) =&gt; {
      if (tag.description) {
        tag.description = tag.description.replace(/\n/g, ' ');
      }
    });

export function parseJsdoc(docs: string): doctrine.Annotation {
  docs = removeLeadingAsterisks(docs);
  const d = doctrine.parse(docs, {
    unwrap: false,
    // lineNumbers: true,
    preserveWhitespace: true,
  });
  // Strip any leading and trailing newline characters in the
  // description of multiline comments for readibility.
  // TODO(rictic): figure out if we can trim() here or not. Something something
  //     markdown?
  const description = d.description && d.description.replace(/^\n+|\n+$/g, '');
  return {description, tags: parseCustomTags(d.tags)};
}

function generateDescription(required, description, type) {
  let deprecated = '';

  if (type.name === 'custom') {
    const deprecatedInfo = getDeprecatedInfo(type);

    if (deprecatedInfo) {
      deprecated = `*Deprecated*. ${deprecatedInfo.explanation}<br><br>`;
    }
  }

  const parsed = parseDoctrine(description);

  // two new lines result in a newline in the table. all other new lines
  // must be eliminated to prevent markdown mayhem.
  const jsDocText = parsed.description.replace(/\n\n/g, '<br>').replace(/\n/g, ' ');

  if (parsed.tags.some(tag =&gt; tag.title === 'ignore')) return null;
  let signature = '';

  if (type.name === 'func' &amp;&amp; parsed.tags.length &gt; 0) {
    // Remove new lines from tag descriptions to avoid markdown errors.
    parsed.tags = parsed.tags.map((tag) =&gt; {
      if (tag.description) {
        return tag.description.replace(/\n/g, ' ');
      }

      return tag;

function generatePropDescription(prop) {
  const { description } = prop;
  const type = prop.flowType || prop.type;
  let deprecated = '';

  if (type.name === 'custom') {
    const deprecatedInfo = getDeprecatedInfo(type);
    if (deprecatedInfo) {
      deprecated = `*Deprecated*. ${deprecatedInfo.explanation}<br><br>`;
    }
  }

  const parsed = parseDoctrine(description, {
    sloppy: true,
  });

  // Two new lines result in a newline in the table.
  // All other new lines must be eliminated to prevent markdown mayhem.
  const jsDocText = escapeCell(parsed.description)
    .replace(/(\r?\n){2}/g, '<br>')
    .replace(/\r?\n/g, ' ');

  if (parsed.tags.some(tag =&gt; tag.title === 'ignore')) {
    return null;
  }

  let signature = '';

  if (type.name === 'func' &amp;&amp; parsed.tags.length &gt; 0) {

Object.keys(doc.props).forEach(propName => {
			const prop = doc.props[propName];
			const doclets = getDocletsObject(prop.description);

			// When a prop is listed in defaultProps but not in props the prop.description is undefined
			const documentation = doctrine.parse(prop.description || '');

			// documentation.description is the description without tags
			doc.props[propName].description = documentation.description;
			doc.props[propName].tags = getDoctrineTags(documentation);

			// Remove ignored props
			if (doclets && doclets.ignore) {
				delete doc.props[propName];
			}
		});
	}

// Parameter with a default: method(param = "default")
    name = nodeParam.left.name;
    defaultValue = generate(nodeParam.right).code;

  } else {
    // Some AST pattern we don't recognize. Hope the code generator does
    // something reasonable.
    name = generate(nodeParam).code;
  }

  let type;
  let description;
  const tag = paramTags.get(name);
  if (tag) {
    if (tag.type) {
      type = doctrine.type.stringify(tag.type);
    }
    if (tag.description) {
      description = tag.description;
    }
  }

  const param: MethodParam = {name, type, defaultValue, rest, description};
  return param;
}