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`.
This commit is contained in:
Peter Bacon Darwin 2015-05-17 21:05:51 +01:00
parent a4693ef679
commit 9407c12923
3 changed files with 80 additions and 4 deletions

View File

@ -0,0 +1,4 @@
export var __esModule = true;
export class OKToExport() {}
export function _thisIsPrivate() {}
export var thisIsOK = '!';

View File

@ -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;
}

View File

@ -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' })
]);
});
});
});