Typo fixes

This commit is contained in:
Jannon 2012-03-09 11:11:00 -08:00
parent eae0a4aea5
commit 4b5f7508bf

View File

@ -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.