+JSDoc has a number of inline tags.
+These are different to its normal tags, because they can occur within the content of other tags.
+The inline tags mainly provide ways to create links or cross-references to other parts of the documentation.
+
+
+
+@tutorial tags form links to tutorials.
+
+
+@link tags form links to everything else: external URLs or other JSDoc symbols.
+Using the @linkcode tag forces the link's text to be rendered in monospace (useful if you are @link-ing to, say, a constant). Using the @linkplain tag keeps the link's text as-is.
+
+
+Furthermore, the configuration optionstemplate.monospaceLinks and templates.cleverLinks can automatically render @link tags in monospace all the time or when the link is non-external respectively.
+
+
+
Links to other symbols
+
+The @link, @linkcode and @linkplain tags allow links to other documented objects or external URLs to be created within doclets.
+
+
+You need to use a symbol's full name to have it linked (e.g. {@link MyNamespace.MyClass#property} rather than MyClass#property).
+Also, remember that @modules, @externals and @events are prefixed by the tag name (e.g. "module:myModule").
+
+
+{{#example}}Linking modules, externals and events.
+/** A module. Refer to it using {@link module:foo/bar}.
+ * @module foo/bar
+ */
+/** The built in string object. Refer to it with {@link external:String}.
+ * @external String
+ */
+/** An event. Refer to with {@link module:foo/bar.event:MyEvent}.
+ * @event module:foo/bar.event:MyEvent
+ */
+{{/example}}
+
+
The @link tag
+{{#example}}Syntax
+{@link someNamepathOrURL}
+[link text here]{@link someNamepathOrURL}
+{@link someNamepathOrURL|link text here}
+{@link someNamepathOrURL Link text here (after the first space)}
+{{/example}}
+
The {@link ...} tag creates a (HTML) link in the generated output to the specified symbol or URL.
+A link text may be provided using the forms specified above.
+If it isn't given, then the URL/symbol path is used as the link text.
+If the symbol path doesn't exist, then the link is not created (the link text is still shown though).
+
+
+{{#example}}Using @link
+/** See {@link MyClass} and [MyClass's foo property]{@link MyClass#foo}.
+ * Also check out {@link http://www.google.com|google} and {@link http://github.com Github}.
+ */
+function myFunction() {}
+
+/** A class.
+ * @class */
+function MyClass() {
+ /** foo property */
+ this.foo = 1;
+}
+{{/example}}
+
+
+The above produces (except that the first two links actually link to the generated documentation for MyClass and MyClass#foo):
+
+By default, {@link ...} just generates HTML <a href="link URL">link text</code>.
+It may be of interest to have link texts always rendered in monospace, particularly if it's a link to another code object. For example, you may want "{@link MY_CONSTANT}" to be rendered MY_CONSTANT rather than MY_CONSTANT.
+
+
+
There are a number of ways to deal with this:
+
+
force a link's text to render in monospace font with @linkcode,
+
force a link's text to render in normal font with @linkplain, or
+
ask JSDoc to make an intelligent guess at how to render @links.
+
+
+
+
Intelligent @link rendering
+
+The configuration optionstemplates.monospaceLinks and templates.cleverLinks can be used to specify how @link captions appear.
+
+
+
+By default both options are switched off. Turn either of them on by modifying your conf.json:
+
+{{#example}}conf.json
+{
+ ...
+ "templates": {
+ // in this example we turn cleverLinks on.
+ "cleverLinks": true,
+ "monospaceLinks": false
+ },
+ ...
+}
+{{/example}}
+
+
+When templates.monospaceLinks is true, all @link tags appear in monospace font.
+For example, "{@link asdf}" will become asdf.
+Use @linkplain if you want a link to not be monospace.
+
+
+
+When templates.cleverLinks is true, @links to external URLs (http or ftp) appear in normal font, while @links to other symbols (like classes, members, functions) will appear in monospace.
+
+
+
+If both options are true, templates.cleverLinks is used.
+
+
+
The @linkplain tag
+{{#example}}Syntax
+{@linkplain someNamepathOrURL}
+[link text here]{@linkplain someNamepathOrURL}
+{@linkplain someNamepathOrURL|link text here}
+{@linkplain someNamepathOrURL Link text here (after the first space)}
+{{/example}}
+
+
+The @linkplain tag is exactly the same as @link, but ensures that the link text is not turned into monospace if you had templates.monospaceLinks or templates.cleverLinks turned on.
+
+
+
+For example, if I turned templates.monospaceLinks on and wrote "{@link fooBar}", it would render fooBar. However, if I write "{@linkplain fooBar}" it will render fooBar.
+
+
+
The @linkcode tag
+{{#example}}Syntax
+{@linkcode someNamepathOrURL}
+[link text here]{@linkcode someNamepathOrURL}
+{@linkcode someNamepathOrURL|link text here}
+{@linkcode someNamepathOrURL Link text here (after the first space)}
+{{/example}}
+
+
+The @linkcode tag is exactly the same as @link, but renders the link caption in monospace.
+For example, "{@linkcode fooBar}" turns into fooBar.
+
+
+
Example
+
+Suppose I had templates.cleverLinks switched on and a file like so:
+
+
+{{#example}}
+/** This is a variable {@link FOO}, cleverLinks makes this monospace.
+ * This is a link to external site {@link http://www.github.com|Github}, not monospace as it's external.
+ * This is a link to {@linkplain FOO}, but we forced it not to be monospace.
+ * This is a link to {@linkcode http://www.github.com Github}, but we forced it to be monospace.
+ * @const
+ */
+var FOO = 1;
+{{/example}}
+
+
+will become:
+
+
+
+This is a variable FOO, cleverLinks makes this monospace.
+This is a link to external site Github, not monospace as it's external.
+This is a link to FOO, but we forced it not to be monospace.
+This is a link to Github, but we forced it to be monospace.
+
+
+
+If we had templates.monospaceLinks on instead, all the links would be monospace except for the "{@linkplain FOO}".
+If we had both options off (the default), all links would be in normal font except for the "{@linkcode http://www.github.com Github}".
+
+In its in-line usage the @tutorial tag is exactly like @link, but for tutorials (and the link text is always in normal font).
+See the tutorials tutorial for more information on setting up tutorials.
+The @tutorial tag may also be used in block format; see the @tutorial page for more information.
+
diff --git a/Jake/articles/about-namepaths b/Jake/articles/about-namepaths
index 591d49bb..c0c10850 100644
--- a/Jake/articles/about-namepaths
+++ b/Jake/articles/about-namepaths
@@ -9,10 +9,10 @@
When referring to a JavaScript variable that is elsewhere in your documentation, you must provide a unique identifier that maps to that variable. A namepath provides a way to do so and disambiguate between instance members, static members and inner variables.
-{{#example}}Basic Syntax Examples of Nameptahs in JSDoc 3
+{{#example}}Basic Syntax Examples of Namepaths in JSDoc 3
myFunction
MyConstructor
-MyConstructor#instancMember
+MyConstructor#instanceMember
MyConstructor.staticMember
MyConstructor~innerMember // note that JSDoc 2 uses a dash
{{/example}}
@@ -82,3 +82,24 @@ In this case, to refer to the method named "consider," you would use the followi
This chaining can be used with any combination of the connecting symbols: # . ~
+
+{{#example}}Special cases: modules, externals and events.
+/** A module. Its name is module:foo/bar.
+ * @module foo/bar
+ */
+/** The built in string object. Its name is external:String.
+ * @external String
+ */
+/** An event. Its name is module:foo/bar.event:MyEvent.
+ * @event module:foo/bar.event:MyEvent
+ */
+{{/example}}
+
+
+There are some special cases with namepaths: @modules are prefixed by "module:", @externals are prefixed by "external:", and @event names are prefixed by "event:".
+
+
+{@link someSymbol}
+{@link http://some.url.com}
+[caption here]{@link someSymbol}
+[caption here]{@link http://some.url.com}
+{@link someSymbol|caption here}
+{@link http://some.url.com|caption here}
+{@link http://some.url.com Caption Here (after the first space)}
+{@link someSymbol Caption Here (after the first space)}
+
+
+The following work in the same way as @link but render in monospace or normal font respectively:
+
+
+{@linkcode ...}
+{@linkplain ...}
+
+
+
Overview
+
+The @link, @linkcode and @linkplain tags allow links to other documented objects or external URLs to be created within doclets (i.e., within the content of other tags).
+
+
+
+You need to use a symbol's full name to have it linked (e.g. {@link MyNamespace.MyClass#property} rather than MyClass#property).
+Also, remember that @modules, @externals and @events are prefixed by the tag name (e.g. "module:myModule").
+
+
+
The {@link ...} tag creates a (HTML) link in the generated output to the specified symbol or URL.
+A link caption different to the link itself may be provided using the syntax specified above.
+If the linked object doesn't exist, then the output is kept as text rather than turned into a link.
+
+
+
+By default, {@link ...} just generates the HTML <a href="link URL">link text</code>.
+It may be of interest to have link texts always rendered in monospace, particularly if it's a link to another code object. For example, you may want "{@link MY_CONSTANT}" to be rendered MY_CONSTANT rather than MY_CONSTANT.
+
+
+
+To achieve this one can use @linkcode. It is exactly the same as @link, but renders the link caption in monospace.
+For example, "{@linkcode fooBar}" turns into fooBar.
+
+
+
+The @linkplain tag is opposite to @linkcode; it ensures that the link text is kept as-is, i.e. not turned into monospace.
+
+
+
+If you want all @links to be rendered in monospace by default, you can set the templates.monospaceLinks option to true in your conf.json.
+If you want @links to be rendered in normal text if they are links to external URLs (http, ftp) and in monospace otherwise, set the templates.cleverLinks option to true in your .
+By default, all @links are rendered in normal font.
+See the configuring JSDoc page for more information on setting these.
+
+
+
+
Examples
+
+{{#example}}Linking modules, externals and events.
+/** A module. Refer to it using {@link module:foo/bar}.
+ * @module foo/bar
+ */
+/** The built in string object. Refer to it with {@link external:String}.
+ * @external String
+ */
+/** An event. Refer to with {@link module:foo/bar.event:MyEvent}.
+ * @event module:foo/bar.event:MyEvent
+ */
+{{/example}}
+
+{{#example}}Using @link
+/** See {@link MyClass} and [MyClass's foo property]{@link MyClass#foo}.
+ * Also check out {@link http://www.google.com|google} and {@link http://github.com Github}.
+ */
+function myFunction() {}
+
+/** A class.
+ * @class */
+function MyClass() {
+ /** foo property */
+ this.foo = 1;
+}
+{{/example}}
+
+
+The above produces (except that the first two links actually link to the generated documentation for MyClass and MyClass#foo):
+
+
+
+{{#example}}Example with @linkplain and @linkcode
+/** This is a variable {@link FOO}, cleverLinks makes this monospace.
+ * This is a link to external site {@link http://www.github.com|Github}, not monospace as it's external.
+ * This is a link to {@linkplain FOO}, but we forced it not to be monospace.
+ * This is a link to {@linkcode http://www.github.com Github}, but we forced it to be monospace.
+ * @const
+ */
+var FOO = 1;
+{{/example}}
+
+
+With the default configuration, this would produce:
+
+This is a variable FOO, cleverLinks makes this monospace.
+This is a link to external site Github, not monospace as it's external.
+This is a link to FOO, but we forced it not to be monospace.
+This is a link to Github, but we forced it to be monospace.
+
+
+
+
+If templates.cleverLinks was on, it would produce:
+
+This is a variable FOO, cleverLinks makes this monospace.
+This is a link to external site Github, not monospace as it's external.
+This is a link to FOO, but we forced it not to be monospace.
+This is a link to Github, but we forced it to be monospace.
+
+
+
+
If template.monospaceLinks was on instead, all the links would be monospace except for the @linkplain.
+
diff --git a/Jake/articles/tags-tutorial b/Jake/articles/tags-tutorial
index 0b888ddd..d1ee7c72 100644
--- a/Jake/articles/tags-tutorial
+++ b/Jake/articles/tags-tutorial
@@ -3,22 +3,45 @@
"out": "tags-tutorial.html",
"description": "Insert a link to an included tutorial file."
}-->
+
Syntax
+
As a block tag:
+@tutorial <tutorialID>
+
+
As an inline tag:
+{@tutorial <tutorialID>}
Overview
-
+
The @tutorial tag can be used both inline and as a normal tag.
+It inserts a link to an included tutorial file.
+See the tutorials tutorial for instructions on creating tutorials.
+JSDoc has a number of inline tags.
+These are different to its normal tags, because they can occur within the content of other tags.
+The inline tags mainly provide ways to create links or cross-references to other parts of the documentation.
+
+
+
+@tutorial tags form links to tutorials.
+
+
+@link tags form links to everything else: external URLs or other JSDoc symbols.
+Using the @linkcode tag forces the link's text to be rendered in monospace (useful if you are @link-ing to, say, a constant). Using the @linkplain tag keeps the link's text as-is.
+
+
+Furthermore, the configuration optionstemplate.monospaceLinks and templates.cleverLinks can automatically render @link tags in monospace all the time or when the link is non-external respectively.
+
+
+
Links to other symbols
+
+The @link, @linkcode and @linkplain tags allow links to other documented objects or external URLs to be created within doclets.
+
+
+You need to use a symbol's full name to have it linked (e.g. {@link MyNamespace.MyClass#property} rather than MyClass#property).
+Also, remember that @modules, @externals and @events are prefixed by the tag name (e.g. "module:myModule").
+
+
+
+
Linking modules, externals and events.
+
+
+/** A module. Refer to it using {@link module:foo/bar}.
+ * @module foo/bar
+ */
+/** The built in string object. Refer to it with {@link external:String}.
+ * @external String
+ */
+/** An event. Refer to with {@link module:foo/bar.event:MyEvent}.
+ * @event module:foo/bar.event:MyEvent
+ */
+
+
+
+
The @link tag
+
+
Syntax
+
+
+{@link someNamepathOrURL}
+[link text here]{@link someNamepathOrURL}
+{@link someNamepathOrURL|link text here}
+{@link someNamepathOrURL Link text here (after the first space)}
+
+
+
+
The {@link ...} tag creates a (HTML) link in the generated output to the specified symbol or URL.
+A link text may be provided using the forms specified above.
+If it isn't given, then the URL/symbol path is used as the link text.
+If the symbol path doesn't exist, then the link is not created (the link text is still shown though).
+
+
+
+
Using @link
+
+
+/** See {@link MyClass} and [MyClass's foo property]{@link MyClass#foo}.
+ * Also check out {@link http://www.google.com|google} and {@link http://github.com Github}.
+ */
+function myFunction() {}
+
+/** A class.
+ * @class */
+function MyClass() {
+ /** foo property */
+ this.foo = 1;
+}
+
+
+
+
+The above produces (except that the first two links actually link to the generated documentation for MyClass and MyClass#foo):
+
+By default, {@link ...} just generates HTML <a href="link URL">link text</code>.
+It may be of interest to have link texts always rendered in monospace, particularly if it's a link to another code object. For example, you may want "{@link MY_CONSTANT}" to be rendered MY_CONSTANT rather than MY_CONSTANT.
+
+
+
There are a number of ways to deal with this:
+
+
force a link's text to render in monospace font with @linkcode,
+
force a link's text to render in normal font with @linkplain, or
+
ask JSDoc to make an intelligent guess at how to render @links.
+
+
+
+
Intelligent @link rendering
+
+The configuration optionstemplates.monospaceLinks and templates.cleverLinks can be used to specify how @link captions appear.
+
+
+
+By default both options are switched off. Turn either of them on by modifying your conf.json:
+
+
+
conf.json
+
+
+{
+ ...
+ "templates": {
+ // in this example we turn cleverLinks on.
+ "cleverLinks": true,
+ "monospaceLinks": false
+ },
+ ...
+}
+
+
+
+
+When templates.monospaceLinks is true, all @link tags appear in monospace font.
+For example, "{@link asdf}" will become asdf.
+Use @linkplain if you want a link to not be monospace.
+
+
+
+When templates.cleverLinks is true, @links to external URLs (http or ftp) appear in normal font, while @links to other symbols (like classes, members, functions) will appear in monospace.
+
+
+
+If both options are true, templates.cleverLinks is used.
+
+
+
The @linkplain tag
+
+
Syntax
+
+
+{@linkplain someNamepathOrURL}
+[link text here]{@linkplain someNamepathOrURL}
+{@linkplain someNamepathOrURL|link text here}
+{@linkplain someNamepathOrURL Link text here (after the first space)}
+
+
+
+
+The @linkplain tag is exactly the same as @link, but ensures that the link text is not turned into monospace if you had templates.monospaceLinks or templates.cleverLinks turned on.
+
+
+
+For example, if I turned templates.monospaceLinks on and wrote "{@link fooBar}", it would render fooBar. However, if I write "{@linkplain fooBar}" it will render fooBar.
+
+
+
The @linkcode tag
+
+
Syntax
+
+
+{@linkcode someNamepathOrURL}
+[link text here]{@linkcode someNamepathOrURL}
+{@linkcode someNamepathOrURL|link text here}
+{@linkcode someNamepathOrURL Link text here (after the first space)}
+
+
+
+
+The @linkcode tag is exactly the same as @link, but renders the link caption in monospace.
+For example, "{@linkcode fooBar}" turns into fooBar.
+
+
+
Example
+
+Suppose I had templates.cleverLinks switched on and a file like so:
+
+
+
+
+
+
+/** This is a variable {@link FOO}, cleverLinks makes this monospace.
+ * This is a link to external site {@link http://www.github.com|Github}, not monospace as it's external.
+ * This is a link to {@linkplain FOO}, but we forced it not to be monospace.
+ * This is a link to {@linkcode http://www.github.com Github}, but we forced it to be monospace.
+ * @const
+ */
+var FOO = 1;
+
+
+
+
+will become:
+
+
+
+This is a variable FOO, cleverLinks makes this monospace.
+This is a link to external site Github, not monospace as it's external.
+This is a link to FOO, but we forced it not to be monospace.
+This is a link to Github, but we forced it to be monospace.
+
+
+
+If we had templates.monospaceLinks on instead, all the links would be monospace except for the "{@linkplain FOO}".
+If we had both options off (the default), all links would be in normal font except for the "{@linkcode http://www.github.com Github}".
+
+
+
Links to other tutorials (@tutorial)
+
+
Syntax
+
+
+{@tutorial tutorialID}
+
+
+
+
+In its in-line usage the @tutorial tag is exactly like @link, but for tutorials (and the link text is always in normal font).
+See the tutorials tutorial for more information on setting up tutorials.
+The @tutorial tag may also be used in block format; see the @tutorial page for more information.
+
+
+
+
Using @tutorial inline.
+
+
+/** Description.
+ * Check out {@tutorial tutorial1} and {@tutorial tutorial2}.
+ * @class
+ */
+
+
myFunction
MyConstructor
-MyConstructor#instancMember
+MyConstructor#instanceMember
MyConstructor.staticMember
MyConstructor~innerMember // note that JSDoc 2 uses a dash
@@ -272,6 +272,31 @@
Namepaths in JSDoc 3
This chaining can be used with any combination of the connecting symbols: # . ~
+
+
Special cases: modules, externals and events.
+
+
+/** A module. Its name is module:foo/bar.
+ * @module foo/bar
+ */
+/** The built in string object. Its name is external:String.
+ * @external String
+ */
+/** An event. Its name is module:foo/bar.event:MyEvent.
+ * @event module:foo/bar.event:MyEvent
+ */
+
+
+
+
+There are some special cases with namepaths: @modules are prefixed by "module:", @externals are prefixed by "external:", and @event names are prefixed by "event:".
+
+
+{@link someSymbol}
+{@link http://some.url.com}
+[caption here]{@link someSymbol}
+[caption here]{@link http://some.url.com}
+{@link someSymbol|caption here}
+{@link http://some.url.com|caption here}
+{@link http://some.url.com Caption Here (after the first space)}
+{@link someSymbol Caption Here (after the first space)}
+
+
+The following work in the same way as @link but render in monospace or normal font respectively:
+
+
+{@linkcode ...}
+{@linkplain ...}
+
+
+
Overview
+
+The @link, @linkcode and @linkplain tags allow links to other documented objects or external URLs to be created within doclets (i.e., within the content of other tags).
+
+
+
+You need to use a symbol's full name to have it linked (e.g. {@link MyNamespace.MyClass#property} rather than MyClass#property).
+Also, remember that @modules, @externals and @events are prefixed by the tag name (e.g. "module:myModule").
+
+
+
The {@link ...} tag creates a (HTML) link in the generated output to the specified symbol or URL.
+A link caption different to the link itself may be provided using the syntax specified above.
+If the linked object doesn't exist, then the output is kept as text rather than turned into a link.
+
+
+
+By default, {@link ...} just generates the HTML <a href="link URL">link text</code>.
+It may be of interest to have link texts always rendered in monospace, particularly if it's a link to another code object. For example, you may want "{@link MY_CONSTANT}" to be rendered MY_CONSTANT rather than MY_CONSTANT.
+
+
+
+To achieve this one can use @linkcode. It is exactly the same as @link, but renders the link caption in monospace.
+For example, "{@linkcode fooBar}" turns into fooBar.
+
+
+
+The @linkplain tag is opposite to @linkcode; it ensures that the link text is kept as-is, i.e. not turned into monospace.
+
+
+
+If you want all @links to be rendered in monospace by default, you can set the templates.monospaceLinks option to true in your conf.json.
+If you want @links to be rendered in normal text if they are links to external URLs (http, ftp) and in monospace otherwise, set the templates.cleverLinks option to true in your .
+By default, all @links are rendered in normal font.
+See the configuring JSDoc page for more information on setting these.
+
+
+
+
Examples
+
+
+
Linking modules, externals and events.
+
+
+/** A module. Refer to it using {@link module:foo/bar}.
+ * @module foo/bar
+ */
+/** The built in string object. Refer to it with {@link external:String}.
+ * @external String
+ */
+/** An event. Refer to with {@link module:foo/bar.event:MyEvent}.
+ * @event module:foo/bar.event:MyEvent
+ */
+
+
+
+
+
Using @link
+
+
+/** See {@link MyClass} and [MyClass's foo property]{@link MyClass#foo}.
+ * Also check out {@link http://www.google.com|google} and {@link http://github.com Github}.
+ */
+function myFunction() {}
+
+/** A class.
+ * @class */
+function MyClass() {
+ /** foo property */
+ this.foo = 1;
+}
+
+
+
+
+The above produces (except that the first two links actually link to the generated documentation for MyClass and MyClass#foo):
+
+/** This is a variable {@link FOO}, cleverLinks makes this monospace.
+ * This is a link to external site {@link http://www.github.com|Github}, not monospace as it's external.
+ * This is a link to {@linkplain FOO}, but we forced it not to be monospace.
+ * This is a link to {@linkcode http://www.github.com Github}, but we forced it to be monospace.
+ * @const
+ */
+var FOO = 1;
+
+
+
+
+With the default configuration, this would produce:
+
+This is a variable FOO, cleverLinks makes this monospace.
+This is a link to external site Github, not monospace as it's external.
+This is a link to FOO, but we forced it not to be monospace.
+This is a link to Github, but we forced it to be monospace.
+
+
+
+
+If templates.cleverLinks was on, it would produce:
+
+This is a variable FOO, cleverLinks makes this monospace.
+This is a link to external site Github, not monospace as it's external.
+This is a link to FOO, but we forced it not to be monospace.
+This is a link to Github, but we forced it to be monospace.
+
+
+
+
If template.monospaceLinks was on instead, all the links would be monospace except for the @linkplain.
+
The @tutorial tag can be used both inline and as a normal tag.
+It inserts a link to an included tutorial file.
+See the tutorials tutorial for instructions on creating tutorials.