docs: added searching aliases (see caolan#1339)

Author: hargasinski

support/jsdoc/jsdoc-custom.js

@@ -1,4 +1,8 @@
 /* eslint no-undef: "off" */
+if (typeof setImmediate !== 'function' && typeof async === 'object') {
+    setImmediate = async.setImmediate;
+}
+
 $(function initSearchBar() {
     function matchSubstrs(methodName) {
         var tokens = [];
@@ -94,12 +98,20 @@ $(function initSearchBar() {
         // handle source files
         } else if (suggestion.indexOf('.html') !== -1) {
             location.href = host + suggestion;
-        // handle searching from one of the source files or the home page
-        } else if (currentPage !== 'docs.html') {
-            location.href = host + 'docs.html#' + suggestion;
         } else {
-            var $el = document.getElementById(suggestion);
-            $('#main-container').animate({ scrollTop: $el.offsetTop - 60 }, 500);
+            var parenIndex = suggestion.indexOf('(');
+            if (parenIndex !== -1) {
+                suggestion = suggestion.substring(0, parenIndex-1);
+            }
+
+            // handle searching from one of the source files or the home page
+            if (currentPage !== 'docs.html') {
+                location.href = host + 'docs.html#' + suggestion;
+            } else {
+                var $el = document.getElementById(suggestion);
+                $('#main-container').animate({ scrollTop: $el.offsetTop - 60 }, 500);
+                location.hash = '#'+suggestion;
+            }
         }
     });
 

support/jsdoc/jsdoc-fix-html.js

@@ -42,29 +42,6 @@ function extractModuleFiles(files) {
     });
 }
 
-function getSearchableInfo($page, callback) {
-    var $sourceLinks = $page.find('a[href$=".js.html"]');
-    var sourceFiles = $sourceLinks.map(function() {
-        return $(this).attr('href');
-    }).toArray().sort();
-
-    var $methodLinks = $page.find('nav').find('a');
-    var methods = $methodLinks.map(function() {
-        var methodName = $(this).text();
-        return (methodName === 'Home' ? null : methodName);
-    }).toArray().sort();
-
-    fs.mkdirsSync(path.join(docsDir, 'data'));
-    async.parallel([
-        function(fileCallback) {
-            fs.writeJson(path.join(docsDir, 'data/sourceFiles.json'), sourceFiles, fileCallback);
-        },
-        function(fileCallback) {
-            fs.writeJson(path.join(docsDir, 'data/methodNames.json'), methods, fileCallback);
-        }
-    ], callback);
-}
-
 function combineFakeModules(files, callback) {
     var moduleFiles = extractModuleFiles(files);
 
@@ -86,11 +63,7 @@ function combineFakeModules(files, callback) {
             });
         }, function(err) {
             if (err) return callback(err);
-
-            getSearchableInfo($mainPage, function(err) {
-                if (err) return callback(err);
-                generateHTMLFile(path.join(docsDir, docFilename), $mainPage, callback);
-            });
+            generateHTMLFile(path.join(docsDir, docFilename), $mainPage, callback);
         });
     });
 }

support/jsdoc/theme/publish.js

@@ -2,7 +2,8 @@
 'use strict';
 
 var doop = require('jsdoc/util/doop');
-var fs = require('jsdoc/fs');
+var fs = require('jsdoc/fs'); // jsdoc/fs offer non-standard functions (mkPath)
+var fsExtra = require('fs-extra');
 var helper = require('jsdoc/util/templateHelper');
 var logger = require('jsdoc/util/logger');
 var path = require('jsdoc/path');
@@ -226,10 +227,12 @@ function generate(type, title, docs, filename, resolveLinks) {
 
 function generateSourceFiles(sourceFiles, encoding) {
     encoding = encoding || 'utf8';
+    var sourceFilenames = [];
     Object.keys(sourceFiles).forEach(function(file) {
         var source;
         // links are keyed to the shortened path in each doclet's `meta.shortpath` property
         var sourceOutfile = helper.getUniqueFilename(sourceFiles[file].shortened);
+        sourceFilenames.push(sourceOutfile);
         helper.registerLink(sourceFiles[file].shortened, sourceOutfile);
 
         try {
@@ -241,9 +244,9 @@ function generateSourceFiles(sourceFiles, encoding) {
         catch(e) {
             logger.error('Error while generating source file %s: %s', file, e.message);
         }
-
         generate('Source', sourceFiles[file].shortened, [source], sourceOutfile, false);
     });
+    return sourceFilenames;
 }
 
 /**
@@ -384,6 +387,40 @@ function buildNav(members) {
     return nav;
 }
 
+/**
+    Sorts an array of strings alphabetically
+    @param {Array<String>} strArr - Array of strings to sort
+    @return {Array<String>} The sorted array
+ */
+function sortStrs(strArr) {
+    return strArr.sort(function(s1, s2) {
+        var lowerCaseS1 = s1.toLowerCase();
+        var lowerCaseS2 = s2.toLowerCase();
+
+        if (lowerCaseS1 < lowerCaseS2) {
+            return -1;
+        } else if (lowerCaseS1 > lowerCaseS2) {
+            return 1;
+        } else {
+            return 0;
+        }
+    });
+}
+
+/**
+    Prints into <outdir>/data a `methodNames.json` and a `sourceFiles.json`
+    JSON file that contains methods and files that can be searched on the
+    generated doc site.
+    @param {Array<String>} methodNames - A list of method names
+    @param {Array<String>} sourceFilenames - A list of source filenames
+ */
+function writeSearchData(methodNames, sourceFilenames) {
+    var dataDir = path.join(outdir, 'data');
+    fsExtra.mkdirsSync(dataDir);
+    fsExtra.writeJsonSync(path.join(dataDir, 'methodNames.json'), sortStrs(methodNames), 'utf8');
+    fsExtra.writeJsonSync(path.join(dataDir, 'sourceFiles.json'), sortStrs(sourceFilenames), 'utf8');
+}
+
 /**
     @param {TAFFY} taffyData See <http://taffydb.com/>.
     @param {object} opts
@@ -537,8 +574,21 @@ exports.publish = function(taffyData, opts, tutorials) {
     });
 
     // do this after the urls have all been generated
+    var methodNames = [];
     data().each(function(doclet) {
         doclet.ancestors = getAncestorLinks(doclet);
+        if (doclet.kind === 'function') {
+            var alias = doclet.alias;
+            var name  = doclet.name;
+            if (alias) {
+                if (Array.isArray(alias)) {
+                    alias = alias.join(', ');
+                }
+                methodNames.push(name + ` (${alias})`);
+            } else {
+                methodNames.push(name);
+            }
+        }
 
         if (doclet.kind === 'member') {
             addSignatureTypes(doclet);
@@ -556,8 +606,8 @@ exports.publish = function(taffyData, opts, tutorials) {
     members.tutorials = tutorials.children;
 
     // output pretty-printed source files by default
-    var outputSourceFiles = conf.default && conf.default.outputSourceFiles !== false 
-        ? true 
+    var outputSourceFiles = conf.default && conf.default.outputSourceFiles !== false
+        ? true
         : false;
 
     // add template helpers
@@ -573,12 +623,15 @@ exports.publish = function(taffyData, opts, tutorials) {
     attachModuleSymbols( find({ longname: {left: 'module:'} }), members.modules );
 
     // generate the pretty-printed source files first so other pages can link to them
+    var sourceFilenames = [];
     if (outputSourceFiles) {
-        generateSourceFiles(sourceFiles, opts.encoding);
+        sourceFilenames = generateSourceFiles(sourceFiles, opts.encoding);
     }
 
-    if (members.globals.length) { 
-        generate('', 'Global', [{kind: 'globalobj'}], globalUrl); 
+    writeSearchData(methodNames, sourceFilenames);
+
+    if (members.globals.length) {
+        generate('', 'Global', [{kind: 'globalobj'}], globalUrl);
     }
 
     // index page displays information from package.json and lists files
@@ -655,6 +708,6 @@ exports.publish = function(taffyData, opts, tutorials) {
             saveChildren(child);
         });
     }
-    
+
     saveChildren(tutorials);
 };

support/jsdoc/theme/tmpl/layout.tmpl

@@ -11,7 +11,7 @@
 
     <link rel="stylesheet" href="styles/prettify-tomorrow.css">
 
-    <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Montserrat:400,700"> 
+    <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Montserrat:400,700">
     <link rel="stylesheet" href="styles/jsdoc-default.css">
 
     <!--[if lt IE 9]>
@@ -86,11 +86,10 @@
 <script src="https://cdn.jsdelivr.net/jquery/2.2.4/jquery.min.js"></script>
 <script src="https://cdn.jsdelivr.net/bootstrap/3.3.6/js/bootstrap.min.js"></script>
 <script src="https://cdn.jsdelivr.net/typeahead.js/0.11.1/typeahead.bundle.min.js"></script>
-
 <script>prettyPrint();</script>
+<script src="scripts/async.js"></script>
+
 <script src="scripts/linenumber.js" async></script>
 <script src="scripts/jsdoc-custom.js" async></script>
-
-<script src="scripts/async.js" async></script>
 </body>
 </html>