Add Polyglot mode, simplify smartGlob to only take extensions

tmcw · tmcw · commit a5bccf032ff8 · 2016-12-26T10:15:03.000-05:00
diff --git a/docs/POLYGLOT.md b/docs/POLYGLOT.md
@@ -0,0 +1,39 @@
+# About documentation.js, polyglot mode, and file extensions
+
+Base assumptions:
+
+* documentation.js subsists on a combination of _source comments_ and
+  _smart inferences from source code_.
+* The default mode of documentation.js is parsing JavaScript, but it has another
+  mode, called `--polyglot` mode, that doesn't include any inference at all
+  and lets you document other kinds of source code.
+* The default settings for everything should work for most projects, but
+  this is a guide for if you have a particular setup.
+
+## File extensions
+
+Let's talk about file extensions. We have two different flags for controlling
+file extensions: `requireExtension` and `parseExtension`.
+
+* requireExtension adds additional filetypes to the node.js `require()` method.
+  By default, you can call, for instance, `require('foo')`, and the require algorithm
+  will look for `foo.js`, `foo` the module, and `foo.json`. Adding another
+  extension in requireExtension lets it look for `foo.otherextension`.
+* parseExtension adds additional filetypes to the list of filetypes documentation.js
+  thinks it can parse, and it also adds those additional filetypes to the default
+  files it looks for when you specify a directory or glob as input.
+
+## Polyglot
+
+Polyglot mode switches documentation.js from running on babylon and [babel](https://babeljs.io/)
+as a JavaScript parser, to using [get-comments](https://github.com/tunnckocore/get-comments).
+This lets it grab comments formatted in the `/** Comment */` style from source
+code that _isn't_ JavaScript, like C++ or CSS code.
+
+Since documentation.js doesn't _parse_ C++ and lots of other languages (parsing JavaScript is complicated enough!),
+it can't make any of its smart inferences about their source code: it just
+takes documentation comments and shows them as-is.
+
+You _can_ use polyglot mode to turn off inference across the board, but I don't recommend
+it. See the 'too much inference' topic in [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
+for detail about that.
diff --git a/lib/smart_glob.js b/lib/smart_glob.js
@@ -26,16 +26,14 @@ function convertPathToPosix(filepath) {
  *
  * Also makes sure all path separators are POSIX style for `glob` compatibility.
  *
- * @param {Object}   [options]                    An options object
- * @param {string[]} [options.extensions=['.js']] An array of accepted extensions
- * @param {string}   [options.cwd=process.cwd()]  The cwd to use to resolve relative pathnames
+ * @param {string[]} [extensions=['.js']] An array of accepted extensions
  * @returns {Function} A function that takes a pathname and returns a glob that
  *                     matches all files with the provided extensions if
  *                     pathname is a directory.
  */
-function processPath(options) {
-  var cwd = (options && options.cwd) || process.cwd();
-  var extensions = (options && options.requireExtension) || ['.js'];
+function processPath(extensions) {
+  var cwd = process.cwd();
+  extensions = extensions || ['.js'];
 
   extensions = extensions.map(function (ext) {
     return ext.replace(/^\./, '');
@@ -71,11 +69,11 @@ function processPath(options) {
 /**
  * Resolves any directory patterns into glob-based patterns for easier handling.
  * @param   {string[]} patterns    File patterns (such as passed on the command line).
- * @param   {Object} options       An options object.
+ * @param   {Array<string>} extensions       A list of file extensions
  * @returns {string[]} The equivalent glob patterns and filepath strings.
  */
-function resolveFileGlobPatterns(patterns, options) {
-  var processPathExtensions = processPath(options);
+function resolveFileGlobPatterns(patterns, extensions) {
+  var processPathExtensions = processPath(extensions);
   return patterns.map(processPathExtensions);
 }
 
@@ -128,9 +126,7 @@ function listFilesToProcess(globPatterns) {
 
 function smartGlob(indexes, extensions) {
   return listFilesToProcess(
-    resolveFileGlobPatterns(indexes, {
-      extensions: extensions
-    })
+    resolveFileGlobPatterns(indexes, extensions)
   );
 }
 
diff --git a/test/bin.js b/test/bin.js
@@ -148,6 +148,19 @@ test('extension option', function (t) {
   });
 });
 
+/*
+ * This tests that parseExtension adds extensions to smartGlob's
+ * look through directories.
+ */
+test('polyglot + parseExtension + smartGlob', function (t) {
+  documentation(['build fixture/polyglot ' +
+    '--polyglot --parseExtension=cpp'], function (err, data) {
+    t.ifError(err);
+    t.equal(data.length, 1, 'includes a file with an arbitrary extension');
+    t.end();
+  });
+});
+
 test('extension option', function (t) {
   documentation(['build fixture/extension.jsx'], function (err, data) {
     t.ifError(err);
