mirror of
https://github.com/jsdoc/jsdoc.git
synced 2025-12-08 19:46:11 +00:00
Typo fixes
This commit is contained in:
parent
eae0a4aea5
commit
4b5f7508bf
@ -78,9 +78,9 @@ source code being documented, like methods provided by a third-party superclass:
|
||||
|
||||
#### Event: jsDocCommentFound
|
||||
|
||||
This is fired whenever a jsdoc comment is found. It may of may not be associate
|
||||
with any code. You might use this to modify the contents of a comment before i
|
||||
t is processed.
|
||||
This is fired whenever a jsdoc comment is found. It may or may not be associate
|
||||
with any code. You might use this to modify the contents of a comment before it
|
||||
is processed.
|
||||
|
||||
The event object will contain the following properties:
|
||||
|
||||
@ -90,11 +90,11 @@ The event object will contain the following properties:
|
||||
|
||||
#### Event: symbolFound
|
||||
|
||||
This is fired when the parser comes across a symbol in the code it thinks are
|
||||
important. This usually means things that one might want to document --
|
||||
variables, functions, object literals, object property definitions,
|
||||
assignments, etc., but the symbols the parser finds can be modified by a plugin
|
||||
(see "Node Visitors" below).
|
||||
This is fired when the parser comes across a symbol in the code it thinks is
|
||||
important. This usually means things that one might want to document --
|
||||
variables, functions, object literals, object property definitions,
|
||||
assignments, etc., but the symbols the parser finds can be modified by a plugin
|
||||
(see "Node Visitors" below).
|
||||
|
||||
The event object will contain the following properties:
|
||||
|
||||
@ -113,7 +113,7 @@ This is the highest level event and is fired when a new doclet has been created.
|
||||
This means that a jsdoc or a symbol has been processed and the actual doclet
|
||||
that will be passed to the template has been created.
|
||||
|
||||
The event object will contains the following properties:
|
||||
The event object will contain the following properties:
|
||||
|
||||
- doclet: the new doclet that was created
|
||||
|
||||
@ -134,7 +134,7 @@ modify the doclet. Some common properties you're likely to see include:
|
||||
- type: the specified type of parameter/property/function return (e.g. Boolean)
|
||||
- params: an object containing the list of parameters to a function
|
||||
- tags: an object containing the set of tags not handled by the parser (note:
|
||||
this is only available in "allowUnknownTags" is set to true in the conf.json
|
||||
this is only available if ```allowUnknownTags``` is set to true in the conf.json
|
||||
file for JSDoc3)
|
||||
|
||||
Below is an example of a newDoclet handler that shouts the descriptions:
|
||||
@ -154,7 +154,7 @@ Below is an example of a newDoclet handler that shouts the descriptions:
|
||||
This is fired when the parser is done with a file. You might use this to
|
||||
perform some cleanup for your plugin.
|
||||
|
||||
The event object will contains the following properties:
|
||||
The event object will contain the following properties:
|
||||
|
||||
- filename: the name of the file
|
||||
- source: the contents of the file
|
||||
@ -163,7 +163,7 @@ The event object will contains the following properties:
|
||||
|
||||
Adding tags to the tag dictionary is a mid-level way to affect documentation
|
||||
generation. Before a newDoclet event is triggered, jsdoc comment blocks are
|
||||
parsed to determine the description and any jsdoc tags that maybe present. When
|
||||
parsed to determine the description and any jsdoc tags that may be present. When
|
||||
a tag is found, if it has been defined in the tag dictionary, it is given a
|
||||
chance to modify the doclet.
|
||||
|
||||
@ -183,15 +183,15 @@ The dictionary provides the following methods:
|
||||
The first parameter is the name of the tag (e.g. "param" or "overview"). the
|
||||
second is an object containing options for the tag. The options can be the
|
||||
following:
|
||||
- mustHaveValue (Boolean): whether or not the tag must have a have
|
||||
- mustHaveValue (Boolean): whether or not the tag must have a value
|
||||
(e.g "@name TheName")
|
||||
- mustNotHaveValue (Boolean): whether or not the tag must not have a value
|
||||
- canHaveType (Boolean): Whether or not the tag can have a type
|
||||
(e.g. "@param {String} name the description of name")
|
||||
- canHaveName (Boolean): Whether or not the tag can have name
|
||||
(e.g. "@param {String} name the description of name")
|
||||
- canHaveType (Boolean): Whether or not the tag can have a type
|
||||
(e.g. "@param **{String}** name the description of name")
|
||||
- canHaveName (Boolean): Whether or not the tag can have a name
|
||||
(e.g. "@param {String} **name** the description of name")
|
||||
- isNamespace (Boolean): Whether or not the tag marks a doclet as representing
|
||||
a namespace. The "@module" tag, for instance sets this to true.
|
||||
a namespace. The "@module" tag, for instance, sets this to true.
|
||||
- onTagged (Function): A callback function executed when the tag is found. The
|
||||
function is passed two parameters: the doclet and the tag. Here's an example:
|
||||
|
||||
@ -222,8 +222,8 @@ defining a node visitor that will visit each node, creating an opportunity to
|
||||
do things like modify comments and trigger parser events for any arbitrary piece
|
||||
of code.
|
||||
|
||||
Plugins can define a node visitor by exporting an _nodeVisitor_ object that
|
||||
contains a _visitNode_ function , like so:
|
||||
Plugins can define a node visitor by exporting a ```nodeVisitor``` object that
|
||||
contains a ```visitNode``` function, like so:
|
||||
|
||||
exports.nodeVisitor = {
|
||||
visitNode: function(node, e, parser, currentSourceName) {
|
||||
@ -235,7 +235,7 @@ The function is called on each node with the following parameters:
|
||||
|
||||
- node: the node of the parse tree
|
||||
- e: the event. If the node is one that the parser handles, this will already
|
||||
be populated with the same things describe in the _sybmolFound_ event above.
|
||||
be populated with the same things described in the _symbolFound_ event above.
|
||||
Otherwise, it will be an empty object on which to set various properties.
|
||||
- parser: the parser
|
||||
- currentSourceName: the name of the file being parsed
|
||||
@ -244,16 +244,16 @@ The function is called on each node with the following parameters:
|
||||
|
||||
The primary reasons to implement a node visitor are to be able to document
|
||||
things that aren't normally documented (like function calls that create classes)
|
||||
or to auto generate documenation for code that isn't documented. For instance,
|
||||
or to auto generate documentation for code that isn't documented. For instance,
|
||||
a plugin might look for calls to a "_trigger" method since it knows that means
|
||||
an event is fired and then generate documentation for the event.
|
||||
|
||||
To make things happen, the _visitNode_ function should madify properties
|
||||
To make things happen, the ```visitNode``` function should modify properties
|
||||
of the event parameter. In general the goal is to construct a comment and then
|
||||
get an event to fire. After the parser lets all of the node visitors have a
|
||||
look at the node, it looks to see if there if the event object has a _comment_
|
||||
property and an _event_ property. If it has both, the event named in the event
|
||||
property is fired. The event is usually "symbolFound" or "jsDocCommentFound",
|
||||
look at the node, it looks to see if the event object has a ```comment```
|
||||
property and an ```event``` property. If it has both, the event named in the event
|
||||
property is fired. The event is usually "symbolFound" or "jsDocCommentFound",
|
||||
but theoretically, a plugin could define its own events and handle them.
|
||||
|
||||
#### Example
|
||||
@ -335,11 +335,10 @@ documentation for the events that are triggered:
|
||||
|
||||
You'll notice a "finishers" property set. The finishers property should contain
|
||||
an array of functions to be called after the event is fired and all the handlers
|
||||
have processed it. The parser provides a "addDocletRef" function that adds the
|
||||
have processed it. The parser provides an ```addDocletRef``` function that adds the
|
||||
doclet to the map (keyed off of the id property) of doclets it knows about.
|
||||
|
||||
Lastly, the visitors are executed in the order the plugins are listed in the
|
||||
conf.json file. A plugin can stop later plugins from visiting a node, by
|
||||
setting a "stopPropagation" property on the event object (e.stopPropagation = true).
|
||||
A plugin can stop the event from firing, but setting a "preventDefault" property.
|
||||
|
||||
Lastly, the visitors are executed in the order the plugins are listed in the
|
||||
conf.json file. A plugin can stop later plugins from visiting a node by
|
||||
setting a ```stopPropagation``` property on the event object (e.stopPropagation = true).
|
||||
A plugin can stop the event from firing, but setting a ```preventDefault``` property.
|
||||
Loading…
x
Reference in New Issue
Block a user