From ba510377da227e21b9b736baea362ce9b000656f Mon Sep 17 00:00:00 2001 From: Patrick Atoon Date: Fri, 2 Jan 2015 13:01:29 +0100 Subject: [PATCH] Adding access parameter --- lib/jsdoc/opts/args.js | 1 + lib/jsdoc/schema.js | 3 +- lib/jsdoc/tag/dictionary/definitions.js | 6 +-- lib/jsdoc/util/templateHelper.js | 15 +++++- test/fixtures/accesstag.js | 10 +++- test/specs/jsdoc/opts/args.js | 22 +++++++++ test/specs/jsdoc/util/templateHelper.js | 62 ++++++++++++++++++++++++- test/specs/tags/accesstag.js | 13 ++++-- 8 files changed, 121 insertions(+), 11 deletions(-) diff --git a/lib/jsdoc/opts/args.js b/lib/jsdoc/opts/args.js index 4748680d..977abed8 100644 --- a/lib/jsdoc/opts/args.js +++ b/lib/jsdoc/opts/args.js @@ -73,6 +73,7 @@ function parseQuery(str) { return result; } +argParser.addOption('a', 'access', true, 'Only display symbols with the given access: "public", "protected", "private" or "undefined". Default: display "public", "protected" and "undefined" symbols', true); argParser.addOption('t', 'template', true, 'The path to the template to use. Default: path/to/jsdoc/templates/default'); argParser.addOption('c', 'configure', true, 'The path to the configuration file. Default: path/to/jsdoc/conf.json'); argParser.addOption('e', 'encoding', true, 'Assume this encoding when reading all source files. Default: utf8'); diff --git a/lib/jsdoc/schema.js b/lib/jsdoc/schema.js index 2de98af0..93fa95a7 100644 --- a/lib/jsdoc/schema.js +++ b/lib/jsdoc/schema.js @@ -222,7 +222,8 @@ var DOCLET_SCHEMA = exports.DOCLET_SCHEMA = { // TODO: define this as an enumeration elsewhere enum: [ 'private', - 'protected' + 'protected', + 'public' ] }, alias: { diff --git a/lib/jsdoc/tag/dictionary/definitions.js b/lib/jsdoc/tag/dictionary/definitions.js index 6c3cf454..3f9a087b 100644 --- a/lib/jsdoc/tag/dictionary/definitions.js +++ b/lib/jsdoc/tag/dictionary/definitions.js @@ -203,8 +203,8 @@ var baseTags = exports.baseTags = { access: { mustHaveValue: true, onTagged: function(doclet, tag) { - // only valid values are private and protected, public is default - if ( /^(private|protected)$/i.test(tag.value) ) { + // only valid values are private, protected and public + if ( /^(private|protected|public)$/i.test(tag.value) ) { doclet.access = tag.value.toLowerCase(); } else { @@ -593,7 +593,7 @@ var baseTags = exports.baseTags = { public: { mustNotHaveValue: true, onTagged: function(doclet, tag) { - delete doclet.access; // public is default + doclet.access = 'public'; } }, readonly: { diff --git a/lib/jsdoc/util/templateHelper.js b/lib/jsdoc/util/templateHelper.js index 8398599e..36012f21 100644 --- a/lib/jsdoc/util/templateHelper.js +++ b/lib/jsdoc/util/templateHelper.js @@ -759,13 +759,26 @@ exports.addEventListeners = function(data) { * + Members tagged `@ignore`. * + Members of anonymous classes. * + Members tagged `@private`, unless the `private` option is enabled. + * + Members tagged with anything other than specified by the `access` options. * @param {TAFFY} data The TaffyDB database to prune. * @return {TAFFY} The pruned database. */ exports.prune = function(data) { data({undocumented: true}).remove(); data({ignore: true}).remove(); - if (!env.opts.private) { data({access: 'private'}).remove(); } + + if (env.opts.access && env.opts.access.indexOf('public') === -1) { + data({access: 'public'}).remove(); + } + if (env.opts.access && env.opts.access.indexOf('protected') === -1) { + data({access: 'protected'}).remove(); + } + if (!env.opts.private && (!env.opts.access || (env.opts.access && env.opts.access.indexOf('private') === -1))) { + data({access: 'private'}).remove(); + } + if (env.opts.access && env.opts.access.indexOf('undefined') === -1) { + data({access: {isUndefined: true}}).remove(); + } data({memberof: ''}).remove(); return data; diff --git a/test/fixtures/accesstag.js b/test/fixtures/accesstag.js index 7d1d8b52..27a4dc40 100644 --- a/test/fixtures/accesstag.js +++ b/test/fixtures/accesstag.js @@ -8,7 +8,10 @@ function Thingy() { this._bar = 1; /** @access public */ - this.pez = 2; + this._gnu = 2; + + /** nothing */ + this.pez = 3; } @@ -24,6 +27,9 @@ function OtherThingy() { this._bar = 1; /** @public */ - this.pez = 2; + this._gnu = 2; + + /** nothing */ + this.pez = 3; } \ No newline at end of file diff --git a/test/specs/jsdoc/opts/args.js b/test/specs/jsdoc/opts/args.js index e88300d2..7a8ebe64 100644 --- a/test/specs/jsdoc/opts/args.js +++ b/test/specs/jsdoc/opts/args.js @@ -109,6 +109,28 @@ describe('jsdoc/opts/args', function() { expect(r.private).toBe(true); }); + it('should accept a "-a" option and return an object with an "access" property', function() { + args.parse(['-a', 'public']); + var r = args.get(); + + expect(r.access).toBe('public'); + }); + + it('should accept a "--access" option and return an object with an "access" property', function() { + args.parse(['--access', 'public']); + var r = args.get(); + + expect(r.access).toBe('public'); + }); + + it('should accept multiple "--access" options and return an object with an "access" property', function() { + args.parse(['--access', 'public', '--access', 'protected']); + var r = args.get(); + + expect(r.access).toContain('public'); + expect(r.access).toContain('protected'); + }); + it('should accept a "-r" option and return an object with a "recurse" property', function() { args.parse(['-r']); var r = args.get(); diff --git a/test/specs/jsdoc/util/templateHelper.js b/test/specs/jsdoc/util/templateHelper.js index e068465d..300cbce0 100644 --- a/test/specs/jsdoc/util/templateHelper.js +++ b/test/specs/jsdoc/util/templateHelper.js @@ -939,9 +939,11 @@ describe("jsdoc/util/templateHelper", function() { describe("prune", function() { var priv = !!global.env.opts.private; + var pub = !!global.env.opts.public; afterEach(function() { global.env.opts.private = priv; + global.env.opts.public = pub; }); var array = [ @@ -958,11 +960,24 @@ describe("jsdoc/util/templateHelper", function() { // prune {memberof: ''} ]; + var keep = [ + // keep + {undocumented: false}, + // keep + {ignore: false}, + // keep + {memberof: 'SomeClass'} + ]; var arrayPrivate = [ // prune (unless env.opts.private is truthy) {access: 'private'} ]; - var keep = array.slice(0, 3); + var arrayMixed = [ + {access: 'public'}, + {asdf: true}, + {access: 'protected'}, + {access: 'private'} + ]; it('should prune the correct members', function() { var pruned = helper.prune( taffy(array) )().get(); @@ -977,6 +992,51 @@ describe("jsdoc/util/templateHelper", function() { compareObjectArrays([], pruned); }); + it('should only keep public members if env.opts.access only contains "public"', function() { + var pruned; + var keepPublic = [{access: 'public'}]; + + global.env.opts.access = 'public'; + pruned = helper.prune( taffy(arrayMixed) )().get(); + compareObjectArrays(keepPublic, pruned); + }); + + it('should only keep undefined members if env.opts.access only contains "undefined"', function() { + var pruned; + var keepUndefined = [{asdf: true}]; + + global.env.opts.access = 'undefined'; + pruned = helper.prune( taffy(arrayMixed) )().get(); + compareObjectArrays(keepUndefined, pruned); + }); + + it('should only keep protected members if env.opts.access only contains "protected"', function() { + var pruned; + var keepProtected = [{access: 'protected'}]; + + global.env.opts.access = 'protected'; + pruned = helper.prune( taffy(arrayMixed) )().get(); + compareObjectArrays(keepProtected, pruned); + }); + + it('should only keep private members if env.opts.access only contains "private"', function() { + var pruned; + var keepPrivate = [{access: 'private'}]; + + global.env.opts.access = 'private'; + pruned = helper.prune( taffy(arrayMixed) )().get(); + compareObjectArrays(keepPrivate, pruned); + }); + + it('should keep public and protected members if env.opts.access contains "public" and "protected"', function() { + var pruned; + var keepPublicProtected = [{access: 'public'}, {access: 'protected'}]; + + global.env.opts.access = ['public', 'protected']; + pruned = helper.prune( taffy(arrayMixed) )().get(); + compareObjectArrays(keepPublicProtected, pruned); + }); + it('should not prune private members if env.opts.private is truthy', function() { var pruned; diff --git a/test/specs/tags/accesstag.js b/test/specs/tags/accesstag.js index b3ae5e03..a61c9b74 100644 --- a/test/specs/tags/accesstag.js +++ b/test/specs/tags/accesstag.js @@ -4,22 +4,29 @@ describe('@access tag', function() { var docSet = jasmine.getDocSetFromFile('test/fixtures/accesstag.js'); var foo = docSet.getByLongname('Thingy~foo')[0]; var _bar = docSet.getByLongname('Thingy#_bar')[0]; + var _gnu = docSet.getByLongname('Thingy#_gnu')[0]; var pez = docSet.getByLongname('Thingy#pez')[0]; var foo2 = docSet.getByLongname('OtherThingy~foo')[0]; var _bar2 = docSet.getByLongname('OtherThingy#_bar')[0]; + var _gnu2 = docSet.getByLongname('OtherThingy#_gnu')[0]; var pez2 = docSet.getByLongname('OtherThingy#pez')[0]; - it("should set the doclet's 'access' property to 'private' when there is an @access private tag", function() { + it('should set the doclet\'s \'access\' property to \'private\' when there is an @access private tag', function() { expect(foo.access).toBe('private'); expect(foo2.access).toBe('private'); }); - it("should set the doclet's 'access' property to 'protected' when there is an @access protected tag", function() { + it('should set the doclet\'s \'access\' property to \'protected\' when there is an @access protected tag', function() { expect(_bar.access).toBe('protected'); expect(_bar2.access).toBe('protected'); }); - it("should set no 'access' property on the doclet when there is an @access public tag", function() { + it('should set the doclet\'s \'access\' property to \'public\' when there is an @access public tag', function() { + expect(_gnu.access).toBe('public'); + expect(_gnu2.access).toBe('public'); + }); + + it('should set no \'access\' property on the doclet when there is no @access tag', function() { expect(pez.access).toBeUndefined(); expect(pez2.access).toBeUndefined(); });