Add @scope tag

[jimbob3806]

Summary

Add @scope tag which behaves identically to the existing @access tag.

Q&A

Q	A
Bug fix?	no
New feature?	yes
Breaking change?	no
Deprecations?	no
Tests added?	no
Fixed issues	none
License	Apache-2.0

Details

Motivation

Add an @scope tag such that methods and members can have scope defined using a generic tag in the same way that methods and members can have access defined using the existing @access tag.

Changes

This change is just a direct copy of the existing definition of the @access tag which may be found here. No changes were made to the functionality of the tag other than to change the tag name, and change the allowed string values in the regex to the set of allowable scope types as defined by the doclet shcema and jsdoc-core names. Case insensitive regex expression was preserved to maintain the behaviour of the existing @access tag which can take access values of mixed cases.

Testing

I could not find any tag-specific tests for the existing @access tag, and since the changes are a essentially a direct copy of the existing jsdoc I did not include tests of any kind.

To verify the behaviour of the changes, I directly added them to the node_modules files in an existing repository using jsdoc (I found this to be quicker and simpler than trying to point to the changed branch). I verified the change by checking the output in generated documentation files, and by inspecting the doclet/ast output using a placeholder plugin with a handler for the parseComplete event. The tag definition was added to the baseTag object exported by node_modules/jsdoc/tag/dictionary/definition.js, the object was altered as follows to test changes:

let baseTags = exports.baseTags = {
    // ... existing jsdoc tags removed for brevity
    // existing jsdoc @access tag
    access: {
        mustHaveValue: true,
        onTagged(doclet, {value}) {
            // only valid values are package, private, protected and public
            if ( /^(package|private|protected|public)$/i.test(value) ) {
                doclet.access = value.toLowerCase();
            }
            else {
                delete doclet.access;
            }
        }
    },
    // ... existing jsdoc tags removed for brevity
    // added @scope tag
    scope: {
        mustHaveValue: true,
        onTagged(doclet, { value }) {
            // only valid scope values are global, instance, static, and inner
            if (/^(global|instance|static|inner)$/i.test(value)) {
            	doclet.scope = value.toLowerCase();
            } else {
            	delete doclet.scope;
            }
        }
    },
    // ... existing jsdoc tags removed for brevity
}