Improve linkerstack internal documentation

Author: tmcw

lib/output/util/linker_stack.js

@@ -55,6 +55,28 @@ function LinkerStack(config) {
   this.link = this.link.bind(this);
 }
 
+/**
+ * Given that the linker stack is a stack of functions, each of which might
+ * be able to resolve the URL target of a given namespace, namespaceResolver
+ * adds a function to the stack. You give it a list of comments and it
+ * adds a function that, if it matches a namespace to a comment, runs
+ * `resolver` on that comment's namespace in order to get a URL. This makes
+ * it possible for themes to put each function on a separate page, or at
+ * different anchors on the same page, and the resolver does stuff like
+ * adding '#' in front of the namespace or turning the namespace into a URL
+ * path.
+ *
+ * @param {Array<Object>} comments a list of comments
+ * @param {Function} a method that turns a namespace into a URL
+ * @returns {LinkerStack} returns this
+ * @private
+ * @example
+ * var linkerStack = createLinkerStack(options)
+ *   .namespaceResolver(comments, function (namespace) {
+ *     var slugger = new GithubSlugger();
+ *     return '#' + slugger.slug(namespace);
+ *   });
+ */
 LinkerStack.prototype.namespaceResolver = function (comments, resolver) {
   var namespaces = {};
   walk(comments, function (comment) {
@@ -68,6 +90,15 @@ LinkerStack.prototype.namespaceResolver = function (comments, resolver) {
   return this;
 };
 
+/**
+ * Now that you've configured the LinkerStack with `namespaceResolver`
+ * and a configuration, run it against a namepath. Might return a URL if
+ * it can resolve a target, otherwise returns undefined.
+ *
+ * @param {string} namepath the namepath of a comment
+ * @returns {string?} URL target or maybe undefined
+ * @private
+ */
 LinkerStack.prototype.link = function (namepath) {
   return firstPass(this.stack, namepath);
 };