Skip to content

Inline tags: Fixes #6 #11

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Jan 31, 2013
Merged

Inline tags: Fixes #6 #11

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
be9da2c
Added stub of inline tags page.
mathematicalcoffee Jan 22, 2013
0ca802e
added tags-link page for @link
mathematicalcoffee Jan 26, 2013
66801b5
filled out tags-tutorial page for @tutorial
mathematicalcoffee Jan 26, 2013
1c6ad4c
added page explaining inline tags @link and @tutorial (about-inline-t…
mathematicalcoffee Jan 26, 2013
077befa
updated index and namepaths pages to point to the new about-inline-ta…
mathematicalcoffee Jan 26, 2013
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
236 changes: 236 additions & 0 deletions Jake/articles/about-inline-tags
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,236 @@
<!--{
title: 'Inline tags',
out: 'about-inline-tags.html',
description: 'Linking with inline tags @link, @linkplain, @linkcode and @tutorial.'
}-->
<p>
<b>Table of Contents</b>
</p>
<ol id="Toc">
<li><a href="#links">Links to other symbols
</a>
<ol>
<li><a href="#link">@link
</a></li>
<li><a href="#configuring-link-output">Intelligent @link rendering.
</a></li>
<li><a href="#linkplain">@linkplain
</a></li>
<li><a href="#linkcode">@linkcode
</a></li>
<li><a href="#link-example">Example
</a></li>
</ol>
</li>
<li><a href="#tutorials">Links to tutorials, @tutorial
</a></li>
<li><a href="#see-also">See also
</a></li>
</ol>

<p>
JSDoc has a number of inline tags.
These are different to its normal tags, because they can occur <em>within</em> the content of other tags.
The inline tags mainly provide ways to create links or cross-references to other parts of the documentation.
</p>

<p>
@tutorial tags form links to tutorials.
</p>
<p>
@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.
</p>
<p>
Furthermore, the <a href="about-configuring-jsdoc.html#configuration-file-templates">configuration options</a> <code>template.monospaceLinks</code> and <code>templates.cleverLinks</code> can automatically render @link tags in monospace all the time or when the link is non-external respectively.
</p>

<h2 id="links" name="links">Links to other symbols</h2>
<p>
The @link, @linkcode and @linkplain tags allow links to other documented objects or external URLs to be created within doclets.
</p>
<p>
You need to use a symbol's full name to have it linked (e.g. <code>{@link MyNamespace.MyClass#property}</code> rather than <code>MyClass#property</code>).
Also, remember that <a href="tags-module.html">@module</a>s, <a href="tags-external.html">@external</a>s and <a href="tags-event.html">@event</a>s are prefixed by the tag name (e.g. "module:myModule").
</p>

{{#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}}

<h3 id="link" name="link">The @link tag</h3>
{{#example}}Syntax
{@link someNamepathOrURL}
[link text here]{@link someNamepathOrURL}
{@link someNamepathOrURL|link text here}
{@link someNamepathOrURL Link text here (after the first space)}
{{/example}}
<p>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).
</p>

{{#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}}

<p>
The above produces (except that the first two links actually link to the generated documentation for MyClass and MyClass#foo):
</p>

<p>
See <a href="#">MyClass</a> and <a href="#">MyClass's foo property</a>.
Also check out <a href="http://www.google.com">google</a> and <a href="http://github.com">Github</a>.
</p>

<p>
By default, {@link ...} just generates HTML <code>&lt;a href="link URL"&gt;link text&lt;/code&gt;</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 <a href="#"><code>MY_CONSTANT</code></a> rather than <a href="#">MY_CONSTANT</a>.
</p>

<p>There are a number of ways to deal with this:
<ul>
<li>force a link's text to render in monospace font with @linkcode,</li>
<li>force a link's text to render in <em>normal</em> font with @linkplain, or</li>
<li>ask JSDoc to make an intelligent guess at how to render @links.</li>
</ul>
</p>

<h3 id="configuring-link-output" name="configuring-link-output">Intelligent @link rendering</h3>
<p>
The <a href="about-configuring-jsdoc.html#configuration-file-templates">configuration options</a> <code>templates.monospaceLinks</code> and <code>templates.cleverLinks</code> can be used to specify how @link captions appear.
</p>

<p>
By default both options are switched off. Turn either of them on by modifying your <code>conf.json</code>:
</p>
{{#example}}conf.json
{
...
"templates": {
// in this example we turn cleverLinks on.
"cleverLinks": true,
"monospaceLinks": false
},
...
}
{{/example}}

<p>
When <code>templates.monospaceLinks</code> is true, all @link tags appear in monospace font.
For example, "{@link asdf}" will become <a href="#">asdf</a>.
Use <a href="#linkplain">@linkplain</a> if you want a link to <em>not</em> be monospace.
</p>

<p>
When <code>templates.cleverLinks</code> 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.
</p>

<p>
If <em>both</em> options are true, <code>templates.cleverLinks</code> is used.
</p>

<h3 id="linkplain" name="linkplain">The @linkplain tag</h3>
{{#example}}Syntax
{@linkplain someNamepathOrURL}
[link text here]{@linkplain someNamepathOrURL}
{@linkplain someNamepathOrURL|link text here}
{@linkplain someNamepathOrURL Link text here (after the first space)}
{{/example}}

<p>
The @linkplain tag is exactly the same as @link, but ensures that the link text is <em>not</em> turned into monospace if you had <code>templates.monospaceLinks</code> or <code>templates.cleverLinks</code> turned on.
</p>

<p>
For example, if I turned <code>templates.monospaceLinks</code> on and wrote "{@link fooBar}", it would render <a href="#"><code>fooBar</code></a>. However, if I write "{@linkplain fooBar}" it will render <a href="#">fooBar</a>.
</p>

<h3 id="linkcode" name="linkcode">The @linkcode tag</h3>
{{#example}}Syntax
{@linkcode someNamepathOrURL}
[link text here]{@linkcode someNamepathOrURL}
{@linkcode someNamepathOrURL|link text here}
{@linkcode someNamepathOrURL Link text here (after the first space)}
{{/example}}

<p>
The @linkcode tag is exactly the same as @link, but renders the link caption in monospace.
For example, "{@linkcode fooBar}" turns into <a href="#"><code>fooBar</code></a>.
</p>

<h3 id="link-example" name="link-example">Example</h3>
<p>
Suppose I had <code>templates.cleverLinks</code> switched on and a file like so:
</p>

{{#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}}

<p>
will become:
</p>

<p>
This is a variable <a href="#"><code>FOO</code></a>, cleverLinks makes this monospace.<br />
This is a link to external site <a href="http://www.github.com">Github</a>, not monospace as it's external.<br />
This is a link to <a href="#">FOO</a>, but we forced it not to be monospace.<br />
This is a link to <a href="http://www.github.com"><code>Github</code></a>, but we forced it to be monospace.
</p>

<p>
If we had <code>templates.monospaceLinks</code> 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}".
</p>

<h2 id="tutorials" name="tutorials">Links to other tutorials (@tutorial)</h2>
{{#example}}Syntax
{@tutorial tutorialID}
{{/example}}

<p>
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 <a href="about-tutorials.html">tutorials tutorial</a> for more information on setting up tutorials.
The @tutorial tag may also be used in block format; see the <a href="tags-tutorial.html">@tutorial</a> page for more information.
</p>

{{#example}}Using @tutorial inline.
/** Description.
* Check out {@tutorial tutorial1} and {@tutorial tutorial2}.
* @class
*/
{{/example}}

<h2 id="see-also" name="see-also">See Also</h2>
<ul>
<li>The <a href="about-tutorials.html">Tutorials tutorial</a></li>
<li><a href="about-namepaths.html">About Namepaths</a></li>
<li>The <a href="tags-tutorial.html">@tutorial</a> tag</li>
<li>The <a href="tags-link.html">@link</a> tag</li>
</ul>
25 changes: 23 additions & 2 deletions Jake/articles/about-namepaths
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
</p>

{{#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}}
Expand Down Expand Up @@ -82,3 +82,24 @@ In this case, to refer to the method named "consider," you would use the followi

<p>
This chaining can be used with any combination of the connecting symbols: <code># . ~</code></p>

{{#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}}

<p>
There are some special cases with namepaths: <a href="tags-module.html">@modules</a> are prefixed by "module:", <a href="tags-external.html">@externals</a> are prefixed by "external:", and <a href="tags-event.html">@event</a> names are prefixed by "event:".
</p>

<h3>See Also</h3>
<ul>
<li><a href="about-inline-tags.html">Inline links within the documentation</a></li>
</ul>
4 changes: 4 additions & 0 deletions Jake/articles/index
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,8 @@
<dd>Additional longtext tutorials for your code.</dd>
<dt><a href="about-including-readme.html">Adding Content to Index.html</a></dt>
<dd>Using Readme files to add content to the default index.html</dd>
<dt><a href="about-inline-tags.html">Linking using inline tags</a></dt>
<dd>All about inline tags @link, @linkplain, @linkcode, @tutorial.</dd>
<dt><a href="about-plugins.html">All about plugins</a></dt>
<dd>Installing plugins and writing your own.</dd>
<dt><a href="plugins-markdown.html">Configuring the markdown plugin</a></dt>
Expand All @@ -62,6 +64,8 @@

<h2 name="JSDoc3_Tag_Dictionary" id="JSDoc3_Tag_Dictionary">JSDoc 3 Tag Dictionary</h2>
<dl>
<dt><a href="about-inline-tags.html">Inline tags</a></dt>
<dd>All about inline tags {@link ...}, {@linkplain ...}, {@linkcode ...}, {@tutorial ...}.</dd>
{{#tagRefEntry}}
{{tagRefEntry}}
{{/tagRefEntry}}
Expand Down
Loading