Skip to content

Commit e6dec4b

Browse files
hegemonichegemonic
committed
document package tag (#167)
1 parent 9ae152c commit e6dec4b

11 files changed

+199
-9
lines changed

‎content/en/tags-access.md

+12-4
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,10 @@
11
---
22
tag: access
3-
description: Specify the access level of this member (private, public, or protected).
3+
description: Specify the access level of this member (private, package-private, public, or protected).
44
related:
55
- tags-global.html
66
- tags-instance.html
7+
- tags-package.html
78
- tags-private.html
89
- tags-protected.html
910
- tags-public.html
@@ -12,14 +13,15 @@ related:
1213

1314
## Syntax
1415

15-
`@access <private|protected|public>`
16+
`@access <package|private|protected|public>`
1617

1718

1819
## Overview
1920

2021
The `@access` tag specifies the access level of a member. You can use the `@access` tag as a
2122
synonym for other tags:
2223

24+
+ `@access package` is the same as `@package`. This option is available in JSDoc 3.5.0 and later.
2325
+ `@access private` is the same as `@private`.
2426
+ `@access protected` is the same as `@protected`.
2527
+ `@access public` is the same as `@public`.
@@ -54,8 +56,11 @@ function Thingy() {
5456
/** @access protected */
5557
this._bar = 1;
5658

59+
/** @access package */
60+
this.baz = 2;
61+
5762
/** @access public */
58-
this.pez = 2;
63+
this.pez = 3;
5964

6065
}
6166

@@ -70,8 +75,11 @@ function OtherThingy() {
7075
/** @protected */
7176
this._bar = 1;
7277

78+
/** @package */
79+
this.baz = 2;
80+
7381
/** @public */
74-
this.pez = 2;
82+
this.pez = 3;
7583

7684
}
7785
```

‎content/en/tags-package.md

+56
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
---
2+
tag: package
3+
description: This symbol is meant to be package-private.
4+
related:
5+
- tags-access.html
6+
- tags-global.html
7+
- tags-instance.html
8+
- tags-private.html
9+
- tags-protected.html
10+
- tags-public.html
11+
- tags-static.html
12+
---
13+
14+
## Syntax
15+
16+
With the JSDoc tag dictionary (enabled by default):
17+
18+
`@package`
19+
20+
With the [Closure Compiler][closure] tag dictionary:
21+
22+
`@package [{typeExpression}]`
23+
24+
[closure]: https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler#jsdoc-tags
25+
26+
27+
## Overview
28+
29+
The `@package` tag marks a symbol as package-private. Typically, this tag indicates that a symbol is
30+
available only to code in the same directory as the source file for this symbol. This tag is
31+
available in JSDoc 3.5.0 and later.
32+
33+
By default, symbols marked with the `@package` tag will appear in your documentation. In JSDoc
34+
3.3.0 and later, you can use the [`-a/--access` command-line option][access-option] to change this
35+
behavior.
36+
37+
The `@package` tag is equivalent to `@access package`.
38+
39+
[access-option]: about-commandline.html
40+
41+
42+
## Examples
43+
44+
In the following example, the instance member `Thingy#_bar` appears in the generated documentation,
45+
but with an annotation indicating that it is package-private:
46+
47+
{% example "Using the @package tag" %}
48+
49+
```js
50+
/** @constructor */
51+
function Thingy() {
52+
/** @package */
53+
this._bar = 1;
54+
}
55+
```
56+
{% endexample %}

‎content/en/tags-private.md

+1
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ related:
55
- tags-access.html
66
- tags-global.html
77
- tags-instance.html
8+
- tags-package.html
89
- tags-protected.html
910
- tags-public.html
1011
- tags-static.html

‎content/en/tags-protected.md

+1
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ related:
55
- tags-access.html
66
- tags-global.html
77
- tags-instance.html
8+
- tags-package.html
89
- tags-private.html
910
- tags-public.html
1011
- tags-static.html

‎content/en/tags-public.md

+1
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ related:
55
- tags-access.html
66
- tags-global.html
77
- tags-instance.html
8+
- tags-package.html
89
- tags-private.html
910
- tags-protected.html
1011
- tags-static.html

‎index.html

+3-1
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@ <h2 id="block-tags">Block Tags</h2>
6565
<dt><a href="tags-abstract.html">@abstract</a> (synonyms: @virtual)</dt>
6666
<dd>This member must be implemented (or overridden) by the inheritor.</dd>
6767
<dt><a href="tags-access.html">@access</a></dt>
68-
<dd>Specify the access level of this member (private, public, or protected).</dd>
68+
<dd>Specify the access level of this member (private, package-private, public, or protected).</dd>
6969
<dt><a href="tags-alias.html">@alias</a></dt>
7070
<dd>Treat a member as if it had a different name.</dd>
7171
<dt><a href="tags-async.html">@async</a></dt>
@@ -152,6 +152,8 @@ <h2 id="block-tags">Block Tags</h2>
152152
<dd>Document a namespace object.</dd>
153153
<dt><a href="tags-override.html">@override</a></dt>
154154
<dd>Indicate that a symbol overrides its parent.</dd>
155+
<dt><a href="tags-package.html">@package</a></dt>
156+
<dd>This symbol is meant to be package-private.</dd>
155157
<dt><a href="tags-param.html">@param</a> (synonyms: @arg, @argument)</dt>
156158
<dd>Document the parameter to a function.</dd>
157159
<dt><a href="tags-private.html">@private</a></dt>

‎tags-access.html

+14-4
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
<head>
66
<meta charset="utf-8">
7-
<meta name="description" content="Specify the access level of this member (private, public, or protected).">
7+
<meta name="description" content="Specify the access level of this member (private, package-private, public, or protected).">
88
<title>Use JSDoc: @access</title>
99
<link rel="stylesheet" href="styles/usejsdoc.css">
1010
<link rel="stylesheet" href="styles/prettify.css">
@@ -38,11 +38,12 @@ <h2>Table of Contents</h2>
3838
</li>
3939
</ul>
4040
<h2 id="syntax">Syntax</h2>
41-
<p><code>@access &lt;private|protected|public&gt;</code>
41+
<p><code>@access &lt;package|private|protected|public&gt;</code>
4242
</p>
4343
<h2 id="overview">Overview</h2>
4444
<p>The <code>@access</code> tag specifies the access level of a member. You can use the <code>@access</code> tag as a synonym for other tags:</p>
4545
<ul>
46+
<li><code>@access package</code> is the same as <code>@package</code>. This option is available in JSDoc 3.5.0 and later.</li>
4647
<li><code>@access private</code> is the same as <code>@private</code>.</li>
4748
<li><code>@access protected</code> is the same as <code>@protected</code>.</li>
4849
<li><code>@access public</code> is the same as <code>@public</code>.</li>
@@ -64,8 +65,11 @@ <h2 id="examples">Examples</h2>
6465
/** @access protected */
6566
this._bar = 1;
6667

68+
/** @access package */
69+
this.baz = 2;
70+
6771
/** @access public */
68-
this.pez = 2;
72+
this.pez = 3;
6973

7074
}
7175

@@ -80,8 +84,11 @@ <h2 id="examples">Examples</h2>
8084
/** @protected */
8185
this._bar = 1;
8286

87+
/** @package */
88+
this.baz = 2;
89+
8390
/** @public */
84-
this.pez = 2;
91+
this.pez = 3;
8592

8693
}
8794
</code></pre>
@@ -94,6 +101,9 @@ <h2 id="related-links">Related Links</h2>
94101
<li>
95102
<a href="tags-instance.html">@instance</a>
96103
</li>
104+
<li>
105+
<a href="tags-package.html">@package</a>
106+
</li>
97107
<li>
98108
<a href="tags-private.html">@private</a>
99109
</li>

‎tags-package.html

+102
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
<!DOCTYPE html>
2+
<!-- THIS IS A GENERATED FILE. DO NOT EDIT. -->
3+
<html lang="en">
4+
5+
<head>
6+
<meta charset="utf-8">
7+
<meta name="description" content="This symbol is meant to be package-private.">
8+
<title>Use JSDoc: @package</title>
9+
<link rel="stylesheet" href="styles/usejsdoc.css">
10+
<link rel="stylesheet" href="styles/prettify.css">
11+
<link rel="stylesheet" href="styles/css3-github-ribbon.css">
12+
<script src="scripts/prettify.js"></script>
13+
<!--[if lt IE 9]>
14+
<script src="scripts/html5shiv.min.js"></script>
15+
<script src="scripts/html5shiv-printshiv.min.js"></script>
16+
<![endif]-->
17+
</head>
18+
19+
<body>
20+
<header>
21+
<a href="./index.html">@use JSDoc</a>
22+
</header>
23+
<article>
24+
<h1>@package</h1>
25+
<h2>Table of Contents</h2>
26+
<ul>
27+
<li>
28+
<a href="#syntax">Syntax</a>
29+
</li>
30+
<li>
31+
<a href="#overview">Overview</a>
32+
</li>
33+
<li>
34+
<a href="#examples">Examples</a>
35+
</li>
36+
<li>
37+
<a href="#related-links">Related Links</a>
38+
</li>
39+
</ul>
40+
<h2 id="syntax">Syntax</h2>
41+
<p>With the JSDoc tag dictionary (enabled by default):</p>
42+
<p><code>@package</code>
43+
</p>
44+
<p>With the <a href="https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler#jsdoc-tags">Closure Compiler</a> tag dictionary:</p>
45+
<p><code>@package [{typeExpression}]</code>
46+
</p>
47+
<h2 id="overview">Overview</h2>
48+
<p>The <code>@package</code> tag marks a symbol as package-private. Typically, this tag indicates that a symbol is available only to code in the same directory
49+
as the source file for this symbol. This tag is available in JSDoc 3.5.0 and later.</p>
50+
<p>By default, symbols marked with the <code>@package</code> tag will appear in your documentation. In JSDoc 3.3.0 and later, you can use the <a href="about-commandline.html"><code>-a/--access</code> command-line option</a> to change this behavior.
51+
</p>
52+
<p>The <code>@package</code> tag is equivalent to <code>@access package</code>.</p>
53+
<h2 id="examples">Examples</h2>
54+
<p>In the following example, the instance member <code>Thingy#_bar</code> appears in the generated documentation, but with an annotation indicating that it is package-private:</p>
55+
<figure>
56+
<figcaption>Using the @package tag</figcaption><pre class="prettyprint lang-js"><code>/** @constructor */
57+
function Thingy() {
58+
/** @package */
59+
this._bar = 1;
60+
}
61+
</code></pre>
62+
</figure>
63+
<h2 id="related-links">Related Links</h2>
64+
<ul>
65+
<li>
66+
<a href="tags-access.html">@access</a>
67+
</li>
68+
<li>
69+
<a href="tags-global.html">@global</a>
70+
</li>
71+
<li>
72+
<a href="tags-instance.html">@instance</a>
73+
</li>
74+
<li>
75+
<a href="tags-private.html">@private</a>
76+
</li>
77+
<li>
78+
<a href="tags-protected.html">@protected</a>
79+
</li>
80+
<li>
81+
<a href="tags-public.html">@public</a>
82+
</li>
83+
<li>
84+
<a href="tags-static.html">@static</a>
85+
</li>
86+
</ul>
87+
</article>
88+
<footer>
89+
<a class="license-badge" href="http://creativecommons.org/licenses/by-sa/3.0/">
90+
<img alt="Creative Commons License" class="license-badge" src="images/cc-by-sa.svg" width="80" height="15" />
91+
</a>
92+
<br> Copyright &#169; 2011-2017 the
93+
<a href="https://github.com/jsdoc3/jsdoc3.github.com/contributors">contributors</a> to the JSDoc 3 documentation project.
94+
<br> This website is <a href="https://github.com/jsdoc3/jsdoc3.github.com">open source</a> and is licensed under the <a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/">
95+
Creative Commons Attribution-ShareAlike 3.0 Unported License</a>.
96+
</footer>
97+
<script type="text/javascript">
98+
prettyPrint();
99+
</script>
100+
</body>
101+
102+
</html>

‎tags-private.html

+3
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,9 @@ <h2 id="related-links">Related Links</h2>
7878
<li>
7979
<a href="tags-instance.html">@instance</a>
8080
</li>
81+
<li>
82+
<a href="tags-package.html">@package</a>
83+
</li>
8184
<li>
8285
<a href="tags-protected.html">@protected</a>
8386
</li>

‎tags-protected.html

+3
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,9 @@ <h2 id="related-links">Related Links</h2>
7171
<li>
7272
<a href="tags-instance.html">@instance</a>
7373
</li>
74+
<li>
75+
<a href="tags-package.html">@package</a>
76+
</li>
7477
<li>
7578
<a href="tags-private.html">@private</a>
7679
</li>

‎tags-public.html

+3
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,9 @@ <h2 id="related-links">Related Links</h2>
6767
<li>
6868
<a href="tags-instance.html">@instance</a>
6969
</li>
70+
<li>
71+
<a href="tags-package.html">@package</a>
72+
</li>
7073
<li>
7174
<a href="tags-private.html">@private</a>
7275
</li>

0 commit comments

Comments
 (0)