Skip to content

Commit 9039c5d

Browse files
hegemonichegemonic
committed
Merge remote-tracking branch 'mathematicalcoffee/inline-tags'
Conflicts: Jake/articles/index index.html
2 parents 52e24d5 + 077befa commit 9039c5d

File tree

9 files changed

+1285
-17
lines changed

9 files changed

+1285
-17
lines changed

‎Jake/articles/about-inline-tags

Lines changed: 236 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,236 @@
1+
<!--{
2+
title: 'Inline tags',
3+
out: 'about-inline-tags.html',
4+
description: 'Linking with inline tags @link, @linkplain, @linkcode and @tutorial.'
5+
}-->
6+
<p>
7+
<b>Table of Contents</b>
8+
</p>
9+
<ol id="Toc">
10+
<li><a href="#links">Links to other symbols
11+
</a>
12+
<ol>
13+
<li><a href="#link">@link
14+
</a></li>
15+
<li><a href="#configuring-link-output">Intelligent @link rendering.
16+
</a></li>
17+
<li><a href="#linkplain">@linkplain
18+
</a></li>
19+
<li><a href="#linkcode">@linkcode
20+
</a></li>
21+
<li><a href="#link-example">Example
22+
</a></li>
23+
</ol>
24+
</li>
25+
<li><a href="#tutorials">Links to tutorials, @tutorial
26+
</a></li>
27+
<li><a href="#see-also">See also
28+
</a></li>
29+
</ol>
30+
31+
<p>
32+
JSDoc has a number of inline tags.
33+
These are different to its normal tags, because they can occur <em>within</em> the content of other tags.
34+
The inline tags mainly provide ways to create links or cross-references to other parts of the documentation.
35+
</p>
36+
37+
<p>
38+
@tutorial tags form links to tutorials.
39+
</p>
40+
<p>
41+
@link tags form links to everything else: external URLs or other JSDoc symbols.
42+
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.
43+
</p>
44+
<p>
45+
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.
46+
</p>
47+
48+
<h2 id="links" name="links">Links to other symbols</h2>
49+
<p>
50+
The @link, @linkcode and @linkplain tags allow links to other documented objects or external URLs to be created within doclets.
51+
</p>
52+
<p>
53+
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>).
54+
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").
55+
</p>
56+
57+
{{#example}}Linking modules, externals and events.
58+
/** A module. Refer to it using {@link module:foo/bar}.
59+
* @module foo/bar
60+
*/
61+
/** The built in string object. Refer to it with {@link external:String}.
62+
* @external String
63+
*/
64+
/** An event. Refer to with {@link module:foo/bar.event:MyEvent}.
65+
* @event module:foo/bar.event:MyEvent
66+
*/
67+
{{/example}}
68+
69+
<h3 id="link" name="link">The @link tag</h3>
70+
{{#example}}Syntax
71+
{@link someNamepathOrURL}
72+
[link text here]{@link someNamepathOrURL}
73+
{@link someNamepathOrURL|link text here}
74+
{@link someNamepathOrURL Link text here (after the first space)}
75+
{{/example}}
76+
<p>The {@link ...} tag creates a (HTML) link in the generated output to the specified symbol or URL.
77+
A link text may be provided using the forms specified above.
78+
If it isn't given, then the URL/symbol path is used as the link text.
79+
If the symbol path doesn't exist, then the link is not created (the link text is still shown though).
80+
</p>
81+
82+
{{#example}}Using @link
83+
/** See {@link MyClass} and [MyClass's foo property]{@link MyClass#foo}.
84+
* Also check out {@link http://www.google.com|google} and {@link http://github.com Github}.
85+
*/
86+
function myFunction() {}
87+
88+
/** A class.
89+
* @class */
90+
function MyClass() {
91+
/** foo property */
92+
this.foo = 1;
93+
}
94+
{{/example}}
95+
96+
<p>
97+
The above produces (except that the first two links actually link to the generated documentation for MyClass and MyClass#foo):
98+
</p>
99+
100+
<p>
101+
See <a href="#">MyClass</a> and <a href="#">MyClass's foo property</a>.
102+
Also check out <a href="http://www.google.com">google</a> and <a href="http://github.com">Github</a>.
103+
</p>
104+
105+
<p>
106+
By default, {@link ...} just generates HTML <code>&lt;a href="link URL"&gt;link text&lt;/code&gt;</code>.
107+
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>.
108+
</p>
109+
110+
<p>There are a number of ways to deal with this:
111+
<ul>
112+
<li>force a link's text to render in monospace font with @linkcode,</li>
113+
<li>force a link's text to render in <em>normal</em> font with @linkplain, or</li>
114+
<li>ask JSDoc to make an intelligent guess at how to render @links.</li>
115+
</ul>
116+
</p>
117+
118+
<h3 id="configuring-link-output" name="configuring-link-output">Intelligent @link rendering</h3>
119+
<p>
120+
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.
121+
</p>
122+
123+
<p>
124+
By default both options are switched off. Turn either of them on by modifying your <code>conf.json</code>:
125+
</p>
126+
{{#example}}conf.json
127+
{
128+
...
129+
"templates": {
130+
// in this example we turn cleverLinks on.
131+
"cleverLinks": true,
132+
"monospaceLinks": false
133+
},
134+
...
135+
}
136+
{{/example}}
137+
138+
<p>
139+
When <code>templates.monospaceLinks</code> is true, all @link tags appear in monospace font.
140+
For example, "{@link asdf}" will become <a href="#">asdf</a>.
141+
Use <a href="#linkplain">@linkplain</a> if you want a link to <em>not</em> be monospace.
142+
</p>
143+
144+
<p>
145+
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.
146+
</p>
147+
148+
<p>
149+
If <em>both</em> options are true, <code>templates.cleverLinks</code> is used.
150+
</p>
151+
152+
<h3 id="linkplain" name="linkplain">The @linkplain tag</h3>
153+
{{#example}}Syntax
154+
{@linkplain someNamepathOrURL}
155+
[link text here]{@linkplain someNamepathOrURL}
156+
{@linkplain someNamepathOrURL|link text here}
157+
{@linkplain someNamepathOrURL Link text here (after the first space)}
158+
{{/example}}
159+
160+
<p>
161+
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.
162+
</p>
163+
164+
<p>
165+
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>.
166+
</p>
167+
168+
<h3 id="linkcode" name="linkcode">The @linkcode tag</h3>
169+
{{#example}}Syntax
170+
{@linkcode someNamepathOrURL}
171+
[link text here]{@linkcode someNamepathOrURL}
172+
{@linkcode someNamepathOrURL|link text here}
173+
{@linkcode someNamepathOrURL Link text here (after the first space)}
174+
{{/example}}
175+
176+
<p>
177+
The @linkcode tag is exactly the same as @link, but renders the link caption in monospace.
178+
For example, "{@linkcode fooBar}" turns into <a href="#"><code>fooBar</code></a>.
179+
</p>
180+
181+
<h3 id="link-example" name="link-example">Example</h3>
182+
<p>
183+
Suppose I had <code>templates.cleverLinks</code> switched on and a file like so:
184+
</p>
185+
186+
{{#example}}
187+
/** This is a variable {@link FOO}, cleverLinks makes this monospace.
188+
* This is a link to external site {@link http://www.github.com|Github}, not monospace as it's external.
189+
* This is a link to {@linkplain FOO}, but we forced it not to be monospace.
190+
* This is a link to {@linkcode http://www.github.com Github}, but we forced it to be monospace.
191+
* @const
192+
*/
193+
var FOO = 1;
194+
{{/example}}
195+
196+
<p>
197+
will become:
198+
</p>
199+
200+
<p>
201+
This is a variable <a href="#"><code>FOO</code></a>, cleverLinks makes this monospace.<br />
202+
This is a link to external site <a href="http://www.github.com">Github</a>, not monospace as it's external.<br />
203+
This is a link to <a href="#">FOO</a>, but we forced it not to be monospace.<br />
204+
This is a link to <a href="http://www.github.com"><code>Github</code></a>, but we forced it to be monospace.
205+
</p>
206+
207+
<p>
208+
If we had <code>templates.monospaceLinks</code> on instead, all the links would be monospace except for the "{@linkplain FOO}".
209+
If we had both options off (the default), all links would be in normal font except for the "{@linkcode http://www.github.com Github}".
210+
</p>
211+
212+
<h2 id="tutorials" name="tutorials">Links to other tutorials (@tutorial)</h2>
213+
{{#example}}Syntax
214+
{@tutorial tutorialID}
215+
{{/example}}
216+
217+
<p>
218+
In its in-line usage the @tutorial tag is exactly like @link, but for tutorials (and the link text is always in normal font).
219+
See the <a href="about-tutorials.html">tutorials tutorial</a> for more information on setting up tutorials.
220+
The @tutorial tag may also be used in block format; see the <a href="tags-tutorial.html">@tutorial</a> page for more information.
221+
</p>
222+
223+
{{#example}}Using @tutorial inline.
224+
/** Description.
225+
* Check out {@tutorial tutorial1} and {@tutorial tutorial2}.
226+
* @class
227+
*/
228+
{{/example}}
229+
230+
<h2 id="see-also" name="see-also">See Also</h2>
231+
<ul>
232+
<li>The <a href="about-tutorials.html">Tutorials tutorial</a></li>
233+
<li><a href="about-namepaths.html">About Namepaths</a></li>
234+
<li>The <a href="tags-tutorial.html">@tutorial</a> tag</li>
235+
<li>The <a href="tags-link.html">@link</a> tag</li>
236+
</ul>

‎Jake/articles/about-namepaths

Lines changed: 23 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,10 @@
99
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.
1010
</p>
1111

12-
{{#example}}Basic Syntax Examples of Nameptahs in JSDoc 3
12+
{{#example}}Basic Syntax Examples of Namepaths in JSDoc 3
1313
myFunction
1414
MyConstructor
15-
MyConstructor#instancMember
15+
MyConstructor#instanceMember
1616
MyConstructor.staticMember
1717
MyConstructor~innerMember // note that JSDoc 2 uses a dash
1818
{{/example}}
@@ -82,3 +82,24 @@ In this case, to refer to the method named "consider," you would use the followi
8282

8383
<p>
8484
This chaining can be used with any combination of the connecting symbols: <code># . ~</code></p>
85+
86+
{{#example}}Special cases: modules, externals and events.
87+
/** A module. Its name is module:foo/bar.
88+
* @module foo/bar
89+
*/
90+
/** The built in string object. Its name is external:String.
91+
* @external String
92+
*/
93+
/** An event. Its name is module:foo/bar.event:MyEvent.
94+
* @event module:foo/bar.event:MyEvent
95+
*/
96+
{{/example}}
97+
98+
<p>
99+
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:".
100+
</p>
101+
102+
<h3>See Also</h3>
103+
<ul>
104+
<li><a href="about-inline-tags.html">Inline links within the documentation</a></li>
105+
</ul>

‎Jake/articles/index

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,8 @@
4040
<dd>About the command-line options JSDoc supports.</dd>
4141
<dt><a href="about-configuring-jsdoc.html">Configuring JSDoc 3 with conf.json</a></dt>
4242
<dd>How to configure JSDoc's output with a configuration file.</dd>
43+
<dt><a href="about-inline-tags.html">Linking using inline tags</a></dt>
44+
<dd>All about inline tags @link, @linkplain, @linkcode, @tutorial.</dd>
4345
<dt><a href="about-plugins.html">All about plugins</a></dt>
4446
<dd>Installing plugins and writing your own.</dd>
4547
<dt><a href="plugins-markdown.html">Configuring the markdown plugin</a></dt>
@@ -66,6 +68,8 @@
6668

6769
<h2 name="JSDoc3_Tag_Dictionary" id="JSDoc3_Tag_Dictionary">JSDoc 3 Tag Dictionary</h2>
6870
<dl>
71+
<dt><a href="about-inline-tags.html">Inline tags</a></dt>
72+
<dd>All about inline tags {@link ...}, {@linkplain ...}, {@linkcode ...}, {@tutorial ...}.</dd>
6973
{{#tagRefEntry}}
7074
{{tagRefEntry}}
7175
{{/tagRefEntry}}

0 commit comments

Comments
 (0)