8000 document columnno property on events; cleanup (#160) · removed-usr/jsdoc.github.io@aca0739 · GitHub
[go: up one dir, main page]
Skip to content

Commit aca0739

Browse files
hegemonichegemonic
committed
document columnno property on events; cleanup (jsdoc#160)
1 parent dda1843 commit aca0739

File tree

2 files changed

+33
-17
lines changed

2 files changed

+33
-17
lines changed

‎about-plugins.html

Lines changed: 13 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -104,7 +104,7 @@ <h4 id="event-beforeparse">Event: beforeParse</h4>
104104
<li><code>filename</code>: The name of the file.</li>
105105
<li><code>source</code>: The contents of the file.</li>
106106
</ul>
107-
<p>Below is an example that adds a virtual doclet for a function to the source so that it will get parsed and added to the documentation. This might be done to
107+
<p>Below is an example that adds a virtual comment for a function to the source so that it will get parsed and added to the documentation. This might be done to
108108
document methods that will be available to users, but might not appear in the source code being documented, such as methods provided by an external superclass:</p>
109109
<figure>
110110
<figcaption>Example</figcaption><pre class="prettyprint lang-js"><code>exports.handlers = {
@@ -130,6 +130,7 @@ <h4 id="event-jsdoccommentfound">Event: jsdocCommentFound</h4>
130130
<li><code>filename</code>: The name of the file.</li>
131131
<li><code>comment</code>: The text of the JSDoc comment.</li>
132132
<li><code>lineno</code>: The line number on which the comment was found.</li& 8000 gt;
133+
<li><code>columnno</code>: The column number on which the comment was found. Available in JSDoc 3.5.0 and later.</li>
133134
</ul>
134135
<h4 id="event-symbolfound">Event: symbolFound</h4>
135136
<p>The <code>symbolFound</code> event is fired when the parser comes across a symbol in the code that may need to be documented. For example, the parser fires a
@@ -140,6 +141,7 @@ <h4 id="event-symbolfound">Event: symbolFound</h4>
140141
<li><code>comment</code>: The text of the comment associated with the symbol, if any.</li>
141142
<li><code>id</code>: The unique ID of the symbol.</li>
142143
<li><code>lineno</code>: The line number on which the symbol was found.</li>
144+
<li><code>columnno</code>: The column number on which the symbol was found. Available in JSDoc 3.5.0 and later.</li>
143145
<li><code>range</code>: An array containing the numeric index of the first and last characters in the source file that are associated with the symbol.</li>
144146
<li><code>astnode</code>: The symbol&#39;s node from the abstract syntax tree.</li>
145147
<li><code>code</code>: Object with detailed information about the code. This object usually contains <code>name</code>,
@@ -171,6 +173,8 @@ <h4 id="event-newdoclet">Event: newDoclet</h4>
171173
<li><code>tags</code>: Object containing a list of tags that JSDoc did not recognize. Only available if
172174
<code>allowUnknownTags</code> is set to <code>true</code> in JSDoc&#39;s configuration file.</li>
173175
</ul>
176+
<p>To see the doclets that JSDoc generates for your code, run JSDoc with the <a href="about-commandline.html"><code>-X</code> command-line
177+
option</a>.</p>
174178
<p>Below is an example of a <code>newDoclet</code> handler that shouts the descriptions:</p>
175179
<figure>
176180
<figcaption>Example</figcaption><pre class="prettyprint lang-js"><code>exports.handlers = {
@@ -197,15 +201,16 @@ <h4 id="event-parsecomplete">Event: parseComplete</h4>
197201
<p>The event object contains the following properties:</p>
198202
<ul>
199203
<li><code>sourcefiles</code>: An array of paths to source files that were parsed.</li>
200-
<li><code>doclets</code>: An array of doclet objects. See the <a href="#event-newdoclet">newDoclet event</a> for details about the properties that each doclet
201-
can contain. <strong>Note</strong>: This property is available in JSDoc 3.2.1 and later.</li>
204+
<li><code>doclets</code>: An array of doclet objects. See the <a href="#event-newdoclet"><code>newDoclet</code> event</a> for details about the properties that
205+
each doclet can contain. Available in JSDoc 3.2.1 and later.</li>
202206
</ul>
203207
<h4 id="event-processingcomplete">Event: processingComplete</h4>
204208
<p>The <code>processingComplete</code> event is fired after JSDoc updates the parse results to reflect inherited and borrowed symbols.</p>
205209
<p><strong>Note</strong>: This event is fired in JSDoc 3.2.1 and later.</p>
206210
<p>The event object contains the following properties:</p>
207211
<ul>
208-
<li>doclets: An array of doclet objects. See the <a href="#event-newdoclet">newDoclet event</a> for details about the properties that each doclet can contain.</li>
212+
<li><code>doclets</code>: An array of doclet objects. See the <a href="#event-newdoclet"><code>newDoclet</code> event</a> for details about the properties that
213+
each doclet can contain.</li>
209214
</ul>
210215
<h3 id="tag-definitions">Tag Definitions</h3>
211216
<p>Adding tags to the tag dictionary is a mid-level way to affect documentation generation. Before a
@@ -276,7 +281,9 @@ <h3 id="node-visitors">Node Visitors</h3>
276281
</figure>
277282
<p>The function is called on each node with the following parameters:</p>
278283
<ul>
279-
<li><code>node</code>: The AST node. AST nodes are JavaScript objects that use the format defined by the Mozilla Parser API. You can use <a href="http://esprima.org/demo/parse.html">Esprima&#39;s parser demo</a> to see the AST that will be created for your source code.</li>
284+
<li><code>node</code>: The AST node. AST nodes are JavaScript objects that use the format defined by the <a href="https://github.com/estree/estree">ESTree
285+
spec</a>. You can use <a href="https://astexplorer.net/">AST Explorer</a> to see the AST that will be created for your source code. As of version 3.5.0, JSDoc uses
286+
the current version of the <a href="https://github.com/babel/babylon">Babylon</a> parser with all plugins enabled.</li>
280287
<li><code>e</code>: The event. If the node is one that the parser handles, the event object will already be populated with the same things described in the <code>symbolFound</code> event above. Otherwise, it will be an empty object on which to set various properties.</li>
281288
<li><code>parser</code>: The JSDoc parser instance.</li>
282289
<li><code>currentSourceName</code>: The name of the file being parsed.</li>
@@ -311,7 +318,7 @@ <h2 id="reporting-errors">Reporting Errors</h2>
311318
logger.error('Oh, no, something bad happened!');
312319
}
313320
}
314-
}
321+
};
315322
</code></pre>
316323
</figure>
317324
</article>

‎content/en/about-plugins.md

Lines changed: 20 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -94,7 +94,7 @@ The event object contains the following properties:
9494
+ `filename`: The name of the file.
9595
+ `source`: The contents of the file.
9696

97-
Below is an example that adds a virtual doclet for a function to the source so that it will get
97+
Below is an example that adds a virtual comment for a function to the source so that it will get
9898
parsed and added to the documentation. This might be done to document methods that will be available
9999
to users, but might not appear in the source code being documented, such as methods provided by an
100100
external superclass:
@@ -129,6 +129,7 @@ The event object contains the following properties:
129129
+ `filename`: The name of the file.
130130
+ `comment`: The text of the JSDoc comment.
131131
+ `lineno`: The line number on which the comment was found.
132+
+ `columnno`: The column number on which the comment was found. Available in JSDoc 3.5.0 and later.
132133

133134
#### Event: symbolFound
134135

@@ -142,6 +143,7 @@ The event object contains the following properties:
142143
+ `comment`: The text of the comment associated with the symbol, if any.
143144
+ `id`: The unique ID of the symbol.
144145
+ `lineno`: The line number on which the symbol was found.
146+
+ `columnno`: The column number on which the symbol was found. Available in JSDoc 3.5.0 and later.
145147
+ `range`: An array containing the numeric index of the first and last characters in the source file
146148
that are associated with the symbol.
147149
+ `astnode`: The symbol's node from the abstract syntax tree.
@@ -182,6 +184,9 @@ or `inner`).
182184
+ `tags`: Object containing a list of tags that JSDoc did not recognize. Only available if
183185
`allowUnknownTags` is set to `true` in JSDoc's configuration file.
184186

187+
To see the doclets that JSDoc generates for your code, run JSDoc with the [`-X` command-line
188+
option][about-commandline].
189+
185190
Below is an example of a `newDoclet` handler that shouts the descriptions:
186191

187192
{% example "Example" %}
@@ -199,6 +204,8 @@ exports.handlers = {
199204
```
200205
{% endexample %}
201206

207+
[about-commandline]: about-commandline.html
208+
202209
#### Event: fileComplete
203210

204211
The `fileComplete` event is fired when the parser has finished parsing a file. Your plugin could use
@@ -218,9 +225,8 @@ The `parseComplete` event is fired after JSDoc has parsed all of the specified s
218225
The event object contains the following properties:
219226

220227
+ `sourcefiles`: An array of paths to source files that were parsed.
221-
+ `doclets`: An array of doclet objects. See the [newDoclet event][newdoclet-event] for details
222-
about the properties that each doclet can contain. **Note**: This property is available in JSDoc
223-
3.2.1 and later.
228+
+ `doclets`: An array of doclet objects. See the [`newDoclet` event][newdoclet-event] for details
229+
about the properties that each doclet can contain. Available in JSDoc 3.2.1 and later.
224230

225231
[newdoclet-event]: #event-newdoclet
226232

@@ -233,8 +239,8 @@ and borrowed symbols.
233239

234240
The event object contains the following properties:
235241

236-
+ doclets: An array of doclet objects. See the [newDoclet event][newdoclet-event] for details about
237-
the properties that each doclet can contain.
242+
+ `doclets`: An array of doclet objects. See the [`newDoclet` event][newdoclet-event] for details
243+
about the properties that each doclet can contain.
238244

239245
[newdoclet-event]: #event-newdoclet
240246

@@ -333,16 +339,19 @@ exports.astNodeVisitor = {
333339

334340
The function is called on each node with the following parameters:
335341

336-
+ `node`: The AST node. AST nodes are JavaScript objects that use the format defined by the Mozilla
337-
Parser API. You can use [Esprima's parser demo][esprima-parser] to see the AST that will be created
338-
for your source code.
342+
+ `node`: The AST node. AST nodes are JavaScript objects that use the format defined by the [ESTree
343+
spec][estree]. You can use [AST Explorer][ast-explorer] to see the AST that will be created for your
344+
source code. As of version 3.5.0, JSDoc uses the current version of the [Babylon][babylon] parser
345+
with all plugins enabled.
339346
+ `e`: The event. If the node is one that the parser handles, the event object will already be
340347
populated with the same things described in the `symbolFound` event above. Otherwise, it will be an
341348
empty object on which to set various properties.
342349
+ `parser`: The JSDoc parser instance.
343350
+ `currentSourceName`: The name of the file being parsed.
344351

345-
[esprima-parser]: http://esprima.org/demo/parse.html
352+
[ast-explorer]: https://astexplorer.net/
353+
[babylon]: https://github.com/babel/babylon
354+
[estree]: https://github.com/estree/estree
346355

347356
#### Making things happen
348357

@@ -390,6 +399,6 @@ exports.handlers = {
390399
logger.error('Oh, no, something bad happened!');
391400
}
392401
}
393-
}
402+
};
394403
```
395404
{% endexample %}

0 commit comments

Comments
 (0)
0