Skip to content

Add migration guide #36

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

Open
shibukawa wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add migration guide #36

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
133 changes: 133 additions & 0 deletions Jake/articles/about-migration
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,133 @@
<!--{
title: 'Migration guide from JSDoc Toolkit',
out: 'about-migration.html',
description: 'About migration guide from JSDoc Toolkit.'
}-->

<p><strong>Table of Contents</strong></p>
<ul>
<li><a href="#different-meaning">Tags that have different meaning with JSDoc 2</a></li>
<li><a href="#convenient-new-feature">Convenient New Features of JSDoc 3</a></li>
</ul>

<p>Comparing to JSDoc Toolkit (JSDoc 2), JSDoc 3 reorganize tags and has more advanced features.
Some reorganization doesn't keep backward-compatibility with JSDoc Toolkit.
There are some tags that have different meaning or/and different parameter types.
This guide provides information how to migrate your JSDoc comment to JSDoc 3.</p>

<h2 name="different-meaning" id="different-meaning">Tags that have different meaning with JSDoc 2</h2>

<dl>
<dt><code>&#64;exports</code></dt>
<dd>Rewrite this tag to the <a href="tags-typedef.html">&#64;typedef</a> tag. The &#64;exports became a tag for module description (see <a href="tags-module.html">&#64;module</a>, <a href="tags-exports.html">&#64;exports</a>).</dd>
<dt><code>&#64;event</code></dt>
<dd>In JSDoc 2, the &#64;event tag is a kind of function (it has same syntax with &#64;function tag), and marked it emits event.
JSDoc 3's <a href="tags-event.html">&#64;event</a> tag is used for describing event object. JSDoc 3 provides a new tag <a href="tags-fires.html">&#64;fires</a> tag instead of JSDoc 2's &#64;event.</dd>
<dt><code>&#64;class</code></dt>
<dd>The syntax and functionality of the &#64;class tag now exactly matches the <a href="tags-constructor.html">&#64;constructor</a> tag.
The new &#64;class tag's parameter meaning is changed from JSDoc 2. It assumes the parameter is a class name
not class's description. Use <a href="tags-classdesc.html">&#64;classdesc</a> tag to write description.</dd>
<dt><code>&#64;fileOverview</code></dt>
<dd>The tag name is changed. Use <a href="tags-file.html">&#64;file</a> tag (or its synonym &quot;&#64;fileoverview&quot;, &quot;&#64;overview&quot;).</dd>
<dt><code>&#64;member</code></dt>
<dd>&quot;&#64;member&quot; was a synonym of the &#64;memberOf, but now it has same meaning of &#64;field of JSDoc 2.
Replace it with <a href="tags-memberof.html">&quot;&#64;memberof&quot;</a>.</dd>
<dt><code>&#64;field</code></dt>
<dd>The tag name is changed to <a href="tags-member.html">&quot;&#64;member&quot;</a>.</dd>
<dt><code>&#64;memberOf</code>, <code>&#64;methodOf</code>, <code>&#64;fieldOf</code></dt>
<dd>Tag name is changed from camelCase to lowercase, <a href="tags-memberof.html">&quot;&#64;memberof&quot;</a>. And &#64;methodOf (&#64;method + &#64;memberOf) and
&#64;filedOf (&#64;filed + &#64;memberOf) are not spported in JSDoc 3. Replace each tag with
&#64;memberof, <a href="tags-method.html">&#64;method</a> + &#64;memberof, <a href="tags-member.html">&#64;member</a> + &#64;memberof.</dd>
<dt><code>&#64;constructs</code></dt>
<dd>JSDoc 2 allows a constructor function's description is following to &#64;constructs tag because JSDoc 2's &#64;constructs doesn't have a parameter.
JSDoc 3's &#64;constructs has a parameter as a class name.
If there was some text after the tag, insert new line.</dd>
<dt><code>&#64;name</code></dt>
<dd>JSDoc 3 provides the <a href="tags-alias.html">&#64;alias</a> tag for just renaming. The &#64;name tag tells JSDoc to ignore all information from source code.
If you want to change the item name, the &#64;alias tag is recommended. <a href="tags-name.html">&#64;name</a> should be used for virtual items (created dynamically in runtime) only.</dd>
<dt><code>&#64;public</code></dt>
<dd>In JSDoc 3, The <a href="tags-public.html">&#64;public</a> tag doesn't affect a symbol's scope. Use the <a href="tags-instance.html">&#64;instance</a>, <a href="tags-static.html">&#64;static</a>, and <a href="tags-global.html">&#64;global</a> to change a symbol's scope.</dd>
<dt><code>&#64;author</code></dt>
<dd><a href="tags-author.html">&#64;author</a> tag can parse E-Mail address following author name. You don’t have to write HTML to add &quot;mailto:&quot; link.</dd>
<dt>Meta tags</dt>
<dd>Meta tags is not supported in JSDoc 3.</dd>
</dl>

<h2 name="convenient-new-feature" id="convenient-new-feature">Convenient New Features of JSDoc 3</h2>
<p>JSDoc 3 provides new attractive features that improves your document's quality:</p>
<p><strong>Long description:</strong></p>
<p>JSDoc 3 has features that import long description instead of just API document created from source files:</p>

<ul>
<li><p><a href="about-including-readme.html">README.md importing</a></p>
<p>It can import README.md as an index page content.</p>
</li>
<li><p><a href="about-tutorials.html">Tutorial</a></p>
<p>It can add long description pages from HTML, Markdown format.</p>
</li>
</ul>

<p><strong>Type specification:</strong></p>

<p>JSDoc 3 starts parsing <a href="tags-type.html">type specification</a>. It can receive more complex types.</p>

<p><strong>Description for new types:</strong></p>

<p>JavaScript is a very flexible language. It has many idioms on the syntax.
JSDoc 3 starts supporting several new idioms.
These new tags help you describe your intention more clearly.</p>
<ul>
<li><p>Callback functions</p>
<p>JSDoc 3 can define a custom type of callback functions by using the <a href="tags-callback.html">&#64;callback</a> tag.</p>
</li>
<li><p>Enumeration</p>
<p>Definition of enumeration table in JSDoc 3 (the <a href="tags-enum.html">&#64;enum</a> tag) is easier than JSDoc 2
(Using &#64;member to each items).</p>
</li>
<li><p>Mix-in</p>
<p>Mix-in is a popular concept in dynamic languages including JavaScript.
JSDoc 3 can document this idiom by using <a href="tags-mixin.html">&#64;mixin</a> and <a href="tags-mixes.html">&#64;mixes</a> tags.</p>
</li>
<li><p>Abstract member</p>
<p>The <a href="tags-abstract.html">&#64;abstract</a> tag identifies members that must be implemented
This member should override by child classes.</p>
</li>
<li><p>Readonly</p>
<p>JSDoc 2 and JSDoc 3 already support the <a href="tags-constant.html">&#64;constant (&#64;const)</a> tag to describe const member.
In addition to that, JSDoc 3 supports the <a href="tags-readonly.html">&#64;readonly</a> tag it can use for getters.</p>
</li>
<li><p>Scope tags</p>
<p>JSDoc adds tags for describing item's scope: <a href="tags-instance.html">&#64;instance</a> (new), <a href="tags-global.html">&#64;global</a> (new), <a href="tags-inner.html">&#64;inner</a>, <a href="tags-static.html">&#64;static</a></p>
</li>
</ul>

<p><strong>Module features:</strong></p>
<p>JavaScript works on many different environment. Some environment supports module features and other environment
has special objects.</p>
<ul>
<li><p>Modules</p>
<p>JSDoc 3 supports a module description including CommonJS style module, a node.js style module, RequireJS style modules
See <a href="tags-module.html">&#64;module</a>, <a href="tags-exports.html">&#64;exports</a> tags documents.</p>
</li>
<li><p>External modules</p>
<p>JSDoc 3 can describe an external or embedded items by using the <a href="tags-external.html">&#64;external</a> tag.
The class or type defined in an external module is usable as a base class or a parameter.</p>
</li>
</ul>
<p><strong>Link text font:</strong></p>
<p>You don't have to write like <code>&lt;code&gt;{&#64;link Symbol}&lt;/code&gt;</code> anymore. JSDoc 3 provides
features to create link with monospace font:</p>
<ul>
<li><a href="about-inline-tags.html"><code>{&#64;linkcode Symbol}</code></a></li>
<li>Turning on <code>template.monospaceLinks</code> or <code>templates.cleverLinks</a> option (described in <a href="about-configuring-jsdoc.html">configuring JSDoc</a>).</li>
</ul>
<p><strong>New tags for more strict, detailed documentation:</strong></p>
<p>JSDoc 3 supports new tags to describe more strict, detailed document.</p>
<ul>
<li><a href="tags-summary.html">&#64;summary</a></li>
<li><a href="tags-kind.html">&#64;kind</a></li>
<li><a href="tags-variation.html">&#64;variation</a></li>
<li><a href="tags-todo.html">&#64;todo</a></li>
<li><a href="tags-copyright.html">&#64;copyright</a></li>
<li><a href="tags-license.html">&#64;license</a></li>
</ul>
2 changes: 2 additions & 0 deletions Jake/articles/index
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,8 @@
<dd>Installing plugins and writing your own.</dd>
<dt><a href="plugins-markdown.html">Configuring the markdown plugin</a></dt>
<dd>This allows markdown in code comments and offers 2 flavors.</dd>
<dt><a href="about-migration.html">Migration Guide from JSDoc Toolkit</a></dt>
<dd>Difference points between JSDoc Toolkit(JSDoc 2) and JSDoc 3.</dd>
<dt><a href="about-testing-jsdoc3.html">Testing JSDoc 3</a></dt>
<dd>About running the self tests included with JSDoc 3.</dd>
<dt><a href="about-license-jsdoc3.html">License</a></dt>
Expand Down
Loading