Revert "Revert "Fix and export link function""

a51a279

Author: jfirebaugh

index.js

@@ -6,10 +6,19 @@ function t(text) {
   return u('text', text);
 }
 
-function link(text) {
-  var docs = globalsDocs.getDoc(text);
-  if (docs) {
-    return u('link', { href: docs }, [u('text', text)]);
+/**
+ * Helper used to automatically link items to global JS documentation or to internal
+ * documentation.
+ *
+ * @param {String} text - text to potentially link
+ * @param {function} [getHref] - a function that tries
+ * to find a URL to point a named link to
+ * @returns {Object} [mdast](https://www.npmjs.com/package/mdast) node
+ */
+function link(text, getHref, description) {
+  var href = (getHref && getHref(text)) || globalsDocs.getDoc(text);
+  if (href) {
+    return u('link', { href: href }, [u('text', description || text)]);
   }
   return u('text', text);
 }
@@ -42,8 +51,8 @@ function decorate(formatted, str, prefix) {
  * Helper used to format JSDoc-style type definitions into HTML or Markdown.
  *
  * @name formatType
- * @param {Object} node type object in doctrine style
- * @param {function(text): text} getNamedLink a function that tries
+ * @param {Object} node - type object in doctrine style
+ * @param {function} getHref - a function that tries
  * to find a URL to point a named link to
  * @returns {Object[]} array of [mdast](https://www.npmjs.com/package/mdast) syntax trees
  * @example
@@ -52,7 +61,7 @@ function decorate(formatted, str, prefix) {
  * // {{ type x }}
  * // generates String
  */
-function formatType(node, getNamedLink) {
+function formatType(node, getHref) {
   var result = [];
 
   if (!node) {
@@ -69,25 +78,25 @@ function formatType(node, getNamedLink) {
   case Syntax.VoidLiteral:
     return [t('void')];
   case Syntax.UndefinedLiteral:
-    return [link('undefined')];
+    return [link('undefined', getHref)];
   case Syntax.NameExpression:
-    return [link(node.name)];
+    return [link(node.name, getHref)];
   case Syntax.ParameterType:
-    return [t(node.name + ': ')].concat(formatType(node.expression, getNamedLink));
+    return [t(node.name + ': ')].concat(formatType(node.expression, getHref));
 
   case Syntax.TypeApplication:
-    return formatType(node.expression, getNamedLink)
-      .concat(commaList(getNamedLink, node.applications, '.<', '>'));
+    return formatType(node.expression, getHref)
+      .concat(commaList(getHref, node.applications, '.<', '>'));
   case Syntax.UnionType:
-    return commaList(getNamedLink, node.elements, '(', ')', '|');
+    return commaList(getHref, node.elements, '(', ')', '|');
   case Syntax.ArrayType:
-    return commaList(getNamedLink, node.elements, '[', ']');
+    return commaList(getHref, node.elements, '[', ']');
   case Syntax.RecordType:
-    return commaList(getNamedLink, node.fields, '{', '}');
+    return commaList(getHref, node.fields, '{', '}');
 
   case Syntax.FieldType:
     if (node.value) {
-      return [t(node.key + ': ')].concat(formatType(node.value, getNamedLink));
+      return [t(node.key + ': ')].concat(formatType(node.value, getHref));
     }
     return [t(node.key)];
 
@@ -101,35 +110,36 @@ function formatType(node, getNamedLink) {
         result.push(t('this: '));
       }
 
-      result = result.concat(formatType(node['this'], getNamedLink));
+      result = result.concat(formatType(node['this'], getHref));
 
       if (node.params.length !== 0) {
         result.push(t(', '));
       }
     }
 
-    result = result.concat(commaList(getNamedLink, node.params, '', ')'));
+    result = result.concat(commaList(getHref, node.params, '', ')'));
 
     if (node.result) {
-      result = result.concat([t(': ')].concat(formatType(node.result, getNamedLink)));
+      result = result.concat([t(': ')].concat(formatType(node.result, getHref)));
     }
     return result;
 
   case Syntax.RestType:
     // note that here we diverge from doctrine itself, which
     // lets the expression be omitted.
-    return decorate(formatType(node.expression, getNamedLink), '...', true);
+    return decorate(formatType(node.expression, getHref), '...', true);
   case Syntax.OptionalType:
-    return decorate(formatType(node.expression, getNamedLink), '=').concat(
+    return decorate(formatType(node.expression, getHref), '=').concat(
         node.default ? t('(default ' + node.default + ')') : []);
   case Syntax.NonNullableType:
-    return decorate(formatType(node.expression, getNamedLink), '!', node.prefix);
+    return decorate(formatType(node.expression, getHref), '!', node.prefix);
   case Syntax.NullableType:
-    return decorate(formatType(node.expression, getNamedLink), '?', node.prefix);
+    return decorate(formatType(node.expression, getHref), '?', node.prefix);
 
   default:
     throw new Error('Unknown type ' + node.type);
   }
 }
 
+module.exports.link = link;
 module.exports.formatType = formatType;

test/format_type.js

@@ -2,6 +2,7 @@
 'use strict';
 
 var formatType = require('../index').formatType,
+  link = require('../index').link,
   remark = require('remark'),
   parse = require('doctrine').parse,
   test = require('tap').test;
@@ -45,6 +46,12 @@ test('formatType', function (t) {
         parse('@param {number} [a=1]', { sloppy: true }).tags[0].type)
   }), '[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)=', 'default');
 
+  t.deepEqual(remark().stringify({
+    type: 'paragraph',
+    children: formatType(
+      parse('@param {Foo} a', { sloppy: true }).tags[0].type, function () { return '#Foo' })
+  }), '[Foo](#Foo)', 'with getHref');
+
   t.deepEqual(formatType(), [], 'empty case');
 
   t.throws(function () {

test/link.js

@@ -0,0 +1,24 @@
+'use strict';
+
+var link = require('../index').link,
+  remark = require('remark'),
+  parse = require('doctrine').parse,
+  test = require('tap').test;
+
+test('link', function (t) {
+  function localURL(text) {
+    if (text === 'Bar') return '#Bar';
+  }
+
+  [
+    ['Array', '[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)'],
+    ['Foo', 'Foo'],
+    ['Foo', 'Foo', localURL],
+    ['Bar', '[Bar](#Bar)', localURL],
+    ['Bar', '[text](#Bar)', localURL, 'text']
+  ].forEach(function (example) {
+    t.deepEqual(remark().stringify(link(example[0], example[2], example[3])), example[1], example[0]);
+  });
+
+  t.end();
+});