add package tag (#962)

lib/jsdoc/opts/args.js

@@ -18,7 +18,7 @@ function parseQuery(str) {
 }
 
 /* eslint-disable no-multi-spaces */
-argParser.addOption('a', 'access',      true,  'Only display symbols with the given access: "public", "protected", "private" or "undefined", or "all" for all access levels. Default: all except "private"', true);
+argParser.addOption('a', 'access',      true,  'Only display symbols with the given access: "package", public", "protected", "private" or "undefined", or "all" for all access levels. Default: all except "private"', true);
 argParser.addOption('c', 'configure',   true,  'The path to the configuration file. Default: path/to/jsdoc/conf.json');
 argParser.addOption('d', 'destination', true,  'The path to the output folder. Use "console" to dump data to the console. Default: ./out/');
 argParser.addOption('',  'debug',       false, 'Log information for debugging JSDoc.');

lib/jsdoc/schema.js

@@ -219,6 +219,7 @@ var DOCLET_SCHEMA = exports.DOCLET_SCHEMA = {
             optional: true,
             // TODO: define this as an enumeration elsewhere
             enum: [
+                'package',
                 'private',
                 'protected',
                 'public'

lib/jsdoc/tag/dictionary/definitions.js

@@ -218,8 +218,8 @@ var baseTags = exports.baseTags = {
     access: {
         mustHaveValue: true,
         onTagged: function(doclet, tag) {
-            // only valid values are private, protected and public
-            if ( /^(private|protected|public)$/i.test(tag.value) ) {
+            // only valid values are package, private, protected and public
+            if ( /^(package|private|protected|public)$/i.test(tag.value) ) {
                 doclet.access = tag.value.toLowerCase();
             }
             else {
@@ -596,6 +596,12 @@ var baseTags = exports.baseTags = {
             setDocletTypeToValueType(doclet, tag);
         }
     },
+    package: {
+        mustNotHaveValue: true,
+        onTagged: function(doclet) {
+            doclet.access = 'package';
+        }
+    },
     param: {
         canHaveType: true,
         canHaveName: true,
@@ -836,6 +842,16 @@ exports.closureTags = {
             doclet.override = true;
         }
     },
+    package: {
+        canHaveType: true,
+        onTagged: function(doclet, tag) {
+            doclet.access = 'package';
+
+            if (tag.value && tag.value.type) {
+                setDocletTypeToValueType(doclet, tag);
+            }
+        }
+    },
     param: cloneTagDef(baseTags.param),
     private: {
         canHaveType: true,

lib/jsdoc/util/templateHelper.js

@@ -895,6 +895,9 @@ exports.prune = function(data) {
     data({memberof: '<anonymous>'}).remove();
 
     if (!env.opts.access || (env.opts.access && env.opts.access.indexOf('all') === -1)) {
+        if (env.opts.access && env.opts.access.indexOf('package') === -1) {
+            data({access: 'package'}).remove();
+        }
         if (env.opts.access && env.opts.access.indexOf('public') === -1) {
             data({access: 'public'}).remove();
         }

test/fixtures/packagetag.js

@@ -0,0 +1,6 @@
+/**
+ * This function is package-private.
+ *
+ * @package
+ */
+function foo() {}

test/fixtures/packagetag2.js

@@ -0,0 +1,8 @@
+/**
+ * @package {Object.<string, number>}
+ */
+var connectionPorts = {
+    'devServer': 6464,
+    'prodServer': 2232,
+    'stagingServer': 4997
+};

test/specs/jsdoc/util/templateHelper.js

@@ -1167,6 +1167,7 @@ describe("jsdoc/util/templateHelper", function() {
             {access: 'private'}
         ];
         var arrayMixed = [
+            {access: 'package'},
             {access: 'public'},
             {asdf: true},
             {access: 'protected'},
@@ -1187,6 +1188,15 @@ describe("jsdoc/util/templateHelper", function() {
             compareObjectArrays([], pruned);
         });
 
+        it('should only keep package-private members if env.opts.access only contains "package"', function() {
+            var pruned;
+            var keepPackage = [{access: 'package'}];
+
+            env.opts.access = 'package';
+            pruned = helper.prune( taffy(arrayMixed) )().get();
+            compareObjectArrays(keepPackage, pruned);
+        });
+
         it('should only keep public members if env.opts.access only contains "public"', function() {
             var pruned;
             var keepPublic = [{access: 'public'}];

test/specs/tags/packagetag.js

@@ -0,0 +1,67 @@
+'use strict';
+
+var definitions = require('jsdoc/tag/dictionary/definitions');
+var dictionary = require('jsdoc/tag/dictionary');
+var Dictionary = dictionary.Dictionary;
+var doclet = require('jsdoc/doclet');
+var logger = require('jsdoc/util/logger');
+
+var originalDictionary = dictionary;
+
+describe('@package tag', function() {
+    var docSet = jasmine.getDocSetFromFile('test/fixtures/packagetag.js');
+    var foo = docSet.getByLongname('foo')[0];
+
+    it('When a symbol has a @package tag, the doclet has an `access` property set to `package`.',
+        function() {
+            expect(foo.access).toBe('package');
+        });
+
+    describe('JSDoc tags', function() {
+        afterEach(function() {
+            doclet._replaceDictionary(originalDictionary);
+        });
+
+        it('When JSDoc tags are enabled, the @package tag does not accept a value.', function() {
+            var dict = new Dictionary();
+
+            definitions.defineTags(dict, definitions.jsdocTags);
+            doclet._replaceDictionary(dict);
+            spyOn(logger, 'warn');
+
+            jasmine.getDocSetFromFile('test/fixtures/packagetag2.js');
+
+            expect(logger.warn).toHaveBeenCalled();
+        });
+    });
+
+    describe('Closure Compiler tags', function() {
+        afterEach(function() {
+            doclet._replaceDictionary(originalDictionary);
+        });
+
+        it('When Closure Compiler tags are enabled, the @package tag accepts a type expression.',
+            function() {
+                var connectionPorts;
+                var dict = new Dictionary();
+                var privateDocs;
+
+                definitions.defineTags(dict, definitions.closureTags);
+                doclet._replaceDictionary(dict);
+                spyOn(logger, 'warn');
+
+                privateDocs = jasmine.getDocSetFromFile('test/fixtures/packagetag2.js');
+                connectionPorts = privateDocs.getByLongname('connectionPorts')[0];
+
+                expect(logger.warn).not.toHaveBeenCalled();
+
+                expect(connectionPorts).toBeDefined();
+                expect(connectionPorts.access).toBe('package');
+
+                expect(connectionPorts.type).toBeDefined();
+                expect(connectionPorts.type.names).toBeDefined();
+                expect(connectionPorts.type.names.length).toBe(1);
+                expect(connectionPorts.type.names[0]).toBe('Object.<string, number>');
+            });
+    });
+});