allow users to specify class attributes for generated links (#331)

lib/jsdoc/util/templateHelper.js

@@ -5,6 +5,8 @@
 
 var crypto = require('crypto');
 var dictionary = require('jsdoc/tag/dictionary');
+var util = require('util');
+
 var hasOwnProp = Object.prototype.hasOwnProperty;
 
 var files = {};
@@ -93,9 +95,17 @@ var tutorialLinkMap = {
 
 var longnameToUrl = exports.longnameToUrl = linkMap.longnameToUrl;
 
-var linkto = exports.linkto = function(longname, linktext) {
+var linkto = exports.linkto = function(longname, linktext, cssClass) {
+    var classString = cssClass ? util.format(' class="%s"', cssClass) : '';
+    var text = linktext || longname;
     var url = longnameToUrl[longname];
-    return url ? '<a href="' + url + '">' + (linktext || longname) + '</a>' : (linktext || longname);
+
+    if (!url) {
+        return text;
+    }
+    else {
+        return util.format('<a href="%s"%s>%s</a>', url, classString, text);
+    }
 };
 
 var htmlsafe = exports.htmlsafe = function(str) {
@@ -181,10 +191,12 @@ exports.getAttribs = function(d) {
 
 /**
  * Retrieve links to allowed types for the member.
- * @param {object} d The doclet whose types will be retrieved.
- * @return {array<string>} HTML links to allowed types for the member.
+ *
+ * @param {Object} d - The doclet whose types will be retrieved.
+ * @param {string} [cssClass] - The CSS class to include in the `class` attribute for each link.
+ * @return {Array.<string>} HTML links to allowed types for the member.
  */
-exports.getSignatureTypes = function(d) {
+exports.getSignatureTypes = function(d, cssClass) {
     var types = [];
     
     if (d.type && d.type.names) {
@@ -193,7 +205,7 @@ exports.getSignatureTypes = function(d) {
     
     if (types && types.length) {
         types = types.map(function(t) {
-            return linkto(t, htmlsafe(t));
+            return linkto(t, htmlsafe(t), cssClass);
         });
     }
 
@@ -231,10 +243,12 @@ exports.getSignatureParams = function(d, optClass) {
 
 /**
  * Retrieve links to types that the member can return.
- * @param {Object} d The doclet whose types will be retrieved.
+ *
+ * @param {Object} d - The doclet whose types will be retrieved.
+ * @param {string} [cssClass] - The CSS class to include in the `class` attribute for each link.
  * @return {Array.<string>} HTML links to types that the member can return.
  */
-exports.getSignatureReturns = function(d) {
+exports.getSignatureReturns = function(d, cssClass) {
     var returnTypes = [];
     
     if (d.returns) {
@@ -249,7 +263,7 @@ exports.getSignatureReturns = function(d) {
     
     if (returnTypes && returnTypes.length) {
         returnTypes = returnTypes.map(function(r) {
-            return linkto(r, htmlsafe(r));
+            return linkto(r, htmlsafe(r), cssClass);
         });
     }
 
@@ -258,11 +272,13 @@ exports.getSignatureReturns = function(d) {
 
 /**
  * Retrieve links to a member's ancestors.
- * @param {TAFFY} data The TaffyDB database to search.
- * @param {object} doclet The doclet whose ancestors will be retrieved.
- * @return {array<string>} HTML links to a member's ancestors.
+ *
+ * @param {TAFFY} data - The TaffyDB database to search.
+ * @param {Object} doclet - The doclet whose ancestors will be retrieved.
+ * @param {string} [cssClass] - The CSS class to include in the `class` attribute for each link.
+ * @return {Array.<string>} HTML links to a member's ancestors.
  */
-exports.getAncestorLinks = function(data, doclet) {
+exports.getAncestorLinks = function(data, doclet, cssClass) {
     var ancestors = [],
         doc = doclet.memberof;
 
@@ -270,7 +286,8 @@ exports.getAncestorLinks = function(data, doclet) {
         doc = find( data, {longname: doc}, false );
         if (doc) { doc = doc[0]; }
         if (!doc) { break; }
-        ancestors.unshift( linkto(doc.longname, (exports.scopeToPunc[doc.scope] || '') + doc.name) );
+        ancestors.unshift( linkto(doc.longname, (exports.scopeToPunc[doc.scope] || '') + doc.name,
+            cssClass) );
         doc = doc.memberof;
     }
     if (ancestors.length) {

test/specs/jsdoc/util/templateHelper.js

@@ -172,8 +172,45 @@ describe("jsdoc/util/templateHelper", function() {
         // TODO
     });
 
-    xdescribe("linkto", function() {
-        // TODO
+    describe("linkto", function() {
+        beforeEach(function() {
+            helper.longnameToUrl.linktoTest = 'test.html';
+        });
+
+        afterEach(function() {
+            delete helper.longnameToUrl.linktoTest;
+        });
+
+        it('returns the longname if only the longname is specified and has no URL', function() {
+            var link = helper.linkto('example');
+            expect(link).toEqual('example');
+        });
+
+        it('returns the link text if only the link text is specified', function() {
+            var link = helper.linkto(null, 'link text');
+            expect(link).toEqual('link text');
+        });
+
+        it('returns the link text if the longname does not have a URL, and both the longname and ' +
+            'link text are specified', function() {
+            var link = helper.linkto('example', 'link text');
+            expect(link).toEqual('link text');
+        });
+
+        it('uses the longname as the link text if no link text is provided', function() {
+            var link = helper.linkto('linktoTest');
+            expect(link).toEqual('<a href="test.html">linktoTest</a>');
+        });
+
+        it('uses the link text if it is specified', function() {
+            var link = helper.linkto('linktoTest', 'link text');
+            expect(link).toEqual('<a href="test.html">link text</a>');
+        });
+        
+        it('includes a "class" attribute in the link if a class is specified', function() {
+            var link = helper.linkto('linktoTest', 'link text', 'myclass');
+            expect(link).toEqual('<a href="test.html" class="myclass">link text</a>');
+        });
     });
 
     xdescribe("htmlsafe", function() {