forked from jsdoc/jsdoc.github.io
-
Notifications
You must be signed in to change notification settings - Fork 0
/
about-tutorials.html
106 lines (103 loc) · 5.23 KB
/
about-tutorials.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
<!DOCTYPE html>
<!-- THIS IS A GENERATED FILE. DO NOT EDIT. -->
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="description" content="Additional longtext tutorials for your code.">
<title>Use JSDoc: Tutorials mechanism</title>
<link rel="stylesheet" href="styles/usejsdoc.css">
<link rel="stylesheet" href="styles/prettify.css">
<link rel="stylesheet" href="styles/css3-github-ribbon.css">
<script src="scripts/prettify.js"></script>
<!--[if lt IE 9]>
<script src="scripts/html5shiv.min.js"></script>
<script src="scripts/html5shiv-printshiv.min.js"></script>
<![endif]-->
</head>
<body>
<header>
<a href="./index.html">@use JSDoc</a>
</header>
<article>
<h1>Tutorials mechanism</h1>
<h2>Table of Contents</h2>
<ul>
<li>
<a href="#configuration">Configuration</a>
</li>
<li>
<a href="#identifiers">Identifiers</a>
<ul>
<li>
<a href="#-tutorial-tag">@tutorial tag</a>
</li>
</ul>
</li>
<li>
<a href="#tutorial-content">Tutorial content</a>
</li>
<li>
<a href="#backward-compatibility">Backward compatibility</a>
</li>
</ul>
<p>Tutorials mechanism allows you to include not only short code-related technical API documentation, but also longer, more explaining, full-page tutorials. It's
a bit similar to phpDocumentor's one.</p>
<p>With <code>-u</code> option you can specify a directory, which JSDoc will search for tutorials. It will treat any file with extension .xml, .xhtml, .html and
.htm as tutorial content files. Also .md and .markdown extensions are supported and will be additionally parsed as Markdown and converted to HTML.</p>
<p>By default each tutorial is top-level. Top-level tutorials are listed in navigation menu.</p>
<h2 id="configuration">Configuration</h2>
<p>Each tutorial file can have additional .js/.json file (with same name, just different extension) which will hold additional tutorial configuration. Two fields
are supported:</p>
<ul>
<li><code>title</code> overrides display name for tutorial with the one specified in it's value (default title for tutorial is it's filename).</li>
<li><code>children</code> which holds list of sub-tutorials identifiers.</li>
</ul>
<p>When tutorial has <code>children</code> property set, it's children will be listed in it's <em>ToC</em> as sub-articles instead of top-level navigation
menu.</p>
<h2 id="identifiers">Identifiers</h2>
<p>Tutorial is identified by it's filename (eg. <code>test.html</code> is named <code>test</code>). No matter to what you will change tutorial's title,
it's identifier will be just <code>test</code>. Title is for displaying, name is for identifying. This allows you to link to tutorial without depending
on it's variable display name.</p>
<h3 id="-tutorial-tag">@tutorial tag</h3>
<p>Doclets can have assigned tutorials (similar to <code>@link</code> and <code>@see</code> tags) through @tutorial tag:</p>
<figure>
<figcaption>Example of the @tutorial tag</figcaption><pre class="prettyprint lang-js"><code>/** * Description.
*
* @class
* @tutorial test-tutorial
*/
</code></pre>
</figure>
<p>@tutorial tag can also be handled in-line in descriptions:</p>
<figure>
<figcaption>Using the tutorial tag in a description</figcaption><pre class="prettyprint lang-js"><code>/**
* Description {@tutorial test-tutorial}.
*
* @class
*/
</code></pre>
</figure>
<h2 id="tutorial-content">Tutorial content</h2>
<p>Tutorial content is processed with <code>resolveLinks()</code>, which means you can use both <code>{@link}</code> and <code>{@tutorial}</code> tags within tutorial
text! They will be processed just like doclets descriptions.</p>
<figure>
<figcaption>Using the @tutorial tag in content</figcaption><pre class="prettyprint lang-html"><code><p>This is tutorial content. See {@link Class.create} for OOP info and {@tutorial class-create} tutorial.</p>
</code></pre>
</figure>
<h2 id="backward-compatibility">Backward compatibility</h2>
<p>It is purely additional feature - if one won't specify <code>-u</code> option it won't affect documentation building. Also template <code>publish()</code> method is not a problem, since tutorials are passed as last argument, so if template function is not prepared for tutorials it just won't process them.</p>
</article>
<footer>
<a class="license-badge" href="http://creativecommons.org/licenses/by-sa/3.0/">
<img alt="Creative Commons License" class="license-badge" src="images/cc-by-sa.svg" width="80" height="15" />
</a>
<br> Copyright © 2011-2014 the
<a href="https://github.com/jsdoc3/jsdoc3.github.com/contributors">contributors</a> to the JSDoc 3 documentation project.
<br> This website is <a href="https://github.com/jsdoc3/jsdoc3.github.com">open source</a> and is licensed under the <a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/">
Creative Commons Attribution-ShareAlike 3.0 Unported License</a>.
</footer>
<script type="text/javascript">
prettyPrint();
</script>
</body>
</html>