From 9407c12923c5dcf081b45bc46317513dc9d7855a Mon Sep 17 00:00:00 2001
From: Peter Bacon Darwin <pete@bacondarwin.com>
Date: Sun, 17 May 2015 21:05:51 +0100
Subject: [PATCH] chore(doc-gen): clarify and improve matching of exports to
 ignore

Previously this was a bit cryptic as we just had a `hideSpecialExports` flag.
Now it ignores exports that match an array of regexes, with the default case
being those exports called `___esModule`.
---
 .../ignoreExportsMatching.ts                  |  4 ++
 .../processors/readTypeScriptModules.js       | 35 +++++++++++++--
 .../processors/readTypeScriptModules.spec.js  | 45 +++++++++++++++++++
 3 files changed, 80 insertions(+), 4 deletions(-)
 create mode 100644 docs/dgeni-package/mocks/readTypeScriptModules/ignoreExportsMatching.ts
 create mode 100644 docs/dgeni-package/processors/readTypeScriptModules.spec.js

diff --git a/docs/dgeni-package/mocks/readTypeScriptModules/ignoreExportsMatching.ts b/docs/dgeni-package/mocks/readTypeScriptModules/ignoreExportsMatching.ts
new file mode 100644
index 0000000000..c3fa704995
--- /dev/null
+++ b/docs/dgeni-package/mocks/readTypeScriptModules/ignoreExportsMatching.ts
@@ -0,0 +1,4 @@
+export var __esModule = true;
+export class OKToExport() {}
+export function _thisIsPrivate() {}
+export var thisIsOK = '!';
\ No newline at end of file
diff --git a/docs/dgeni-package/processors/readTypeScriptModules.js b/docs/dgeni-package/processors/readTypeScriptModules.js
index 700252fcf0..81c4985ec0 100644
--- a/docs/dgeni-package/processors/readTypeScriptModules.js
+++ b/docs/dgeni-package/processors/readTypeScriptModules.js
@@ -13,17 +13,23 @@ module.exports = function readTypeScriptModules(tsParser, readFilesProcessor, mo
       sourceFiles: {presence: true},
       basePath: {presence: true},
       hidePrivateMembers: { inclusion: [true, false] },
-      hideSpecialExports: { inclusion: [true, false] }
+      ignoreExportsMatching: {}
     },
 
+    // A collection of globs that identify those modules for which we should create docs
     sourceFiles: [],
+    // The base path from which to load the source files
     basePath: '.',
+    // We can ignore members of classes that are private
     hidePrivateMembers: false,
-    hideSpecialExports: true,
+    // We can provide a collection of strings or regexes to ignore exports whose export names match
+    ignoreExportsMatching: ['___esModule'],
 
     $process: function(docs) {
 
-      var hideSpecialExports = this.hideSpecialExports;
+      // Convert ignoreExportsMatching to an array of regexes
+      var ignoreExportsMatching = convertToRegexCollection(this.ignoreExportsMatching);
+
       var hidePrivateMembers = this.hidePrivateMembers;
 
       var basePath = path.resolve(readFilesProcessor.basePath, this.basePath);
@@ -45,7 +51,7 @@ module.exports = function readTypeScriptModules(tsParser, readFilesProcessor, mo
         moduleSymbol.exportArray.forEach(function(exportSymbol) {
 
           // Ignore exports starting with an underscore
-          if (hideSpecialExports && exportSymbol.name.charAt(0) === '_') return;
+          if (anyMatches(ignoreExportsMatching, exportSymbol.name)) return;
 
           // If the symbol is an Alias then for most things we want the original resolved symbol
           var resolvedExport = exportSymbol.resolvedSymbol || exportSymbol;
@@ -199,3 +205,24 @@ function insertSorted(collection, item, property) {
   }
   collection.splice(index, 0, item);
 }
+
+function convertToRegexCollection(items) {
+  if (!items) return [];
+
+  // Must be an array
+  if (!_.isArray(items)) {
+    items = [items];
+  }
+
+  // Convert string to exact matching regexes
+  return items.map(function(item) {
+    return _.isString(item) ? new RegExp('^' + item + '$') : item;
+  });
+}
+
+function anyMatches(regexes, item) {
+  for(var i=0; i<regexes.length; ++i) {
+    if ( item.match(regexes[i]) ) return true;
+  }
+  return false;
+}
\ No newline at end of file
diff --git a/docs/dgeni-package/processors/readTypeScriptModules.spec.js b/docs/dgeni-package/processors/readTypeScriptModules.spec.js
new file mode 100644
index 0000000000..0a9e2bedb4
--- /dev/null
+++ b/docs/dgeni-package/processors/readTypeScriptModules.spec.js
@@ -0,0 +1,45 @@
+var mockPackage = require('../mocks/mockPackage');
+var Dgeni = require('dgeni');
+var path = require('canonical-path');
+
+describe('readTypeScriptModules', function() {
+  var dgeni, injector, processor;
+
+  beforeEach(function() {
+    dgeni = new Dgeni([mockPackage()]);
+    injector = dgeni.configureInjector();
+    processor = injector.get('readTypeScriptModules');
+    processor.basePath = path.resolve(__dirname, '../mocks/');
+  });
+
+
+  describe('ignoreExportsMatching', function() {
+    it('should ignore exports that match items in the `ignoreExportsMatching` property', function() {
+      processor.sourceFiles = [ 'readTypeScriptModules/ignoreExportsMatching.ts'];
+      processor.ignoreExportsMatching = [/^_/];
+      var docs = [];
+      processor.$process(docs);
+
+      var moduleDoc = docs[0];
+      expect(moduleDoc.docType).toEqual('module');
+      expect(moduleDoc.exports).toEqual([
+        jasmine.objectContaining({ name: 'OKToExport' }),
+        jasmine.objectContaining({ name: 'thisIsOK' })
+      ]);
+    });
+
+    it('should only ignore `___esModule` exports by default', function() {
+      processor.sourceFiles = [ 'readTypeScriptModules/ignoreExportsMatching.ts'];
+      var docs = [];
+      processor.$process(docs);
+
+      var moduleDoc = docs[0];
+      expect(moduleDoc.docType).toEqual('module');
+      expect(moduleDoc.exports).toEqual([
+        jasmine.objectContaining({ name: 'OKToExport' }),
+        jasmine.objectContaining({ name: '_thisIsPrivate' }),
+        jasmine.objectContaining({ name: 'thisIsOK' })
+      ]);
+    });
+  });
+});
\ No newline at end of file