From 02769bd141c5ce708ae8af3c400d431c96b2abe7 Mon Sep 17 00:00:00 2001 From: Yoshiki Shibukawa Date: Mon, 22 Apr 2013 09:43:07 -0700 Subject: [PATCH] Add migration guide --- Jake/articles/about-migration | 133 ++++++++++++++ Jake/articles/index | 2 + about-migration.html | 318 ++++++++++++++++++++++++++++++++++ index.html | 2 + 4 files changed, 455 insertions(+) create mode 100644 Jake/articles/about-migration create mode 100644 about-migration.html diff --git a/Jake/articles/about-migration b/Jake/articles/about-migration new file mode 100644 index 00000000..c5d00b0c --- /dev/null +++ b/Jake/articles/about-migration @@ -0,0 +1,133 @@ + + +

Table of Contents

+ + +

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.

+ +

Tags that have different meaning with JSDoc 2

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

Convenient New Features of JSDoc 3

+

JSDoc 3 provides new attractive features that improves your document's quality:

+

Long description:

+

JSDoc 3 has features that import long description instead of just API document created from source files:

+ + + +

Type specification:

+ +

JSDoc 3 starts parsing type specification. It can receive more complex types.

+ +

Description for new types:

+ +

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.

+ + +

Module features:

+

JavaScript works on many different environment. Some environment supports module features and other environment +has special objects.

+ +

Link text font:

+

You don't have to write like <code>{@link Symbol}</code> anymore. JSDoc 3 provides +features to create link with monospace font:

+ +

New tags for more strict, detailed documentation:

+

JSDoc 3 supports new tags to describe more strict, detailed document.

+ diff --git a/Jake/articles/index b/Jake/articles/index index 913e3b50..45ae7afa 100644 --- a/Jake/articles/index +++ b/Jake/articles/index @@ -46,6 +46,8 @@
Installing plugins and writing your own.
Configuring the markdown plugin
This allows markdown in code comments and offers 2 flavors.
+
Migration Guide from JSDoc Toolkit
+
Difference points between JSDoc Toolkit(JSDoc 2) and JSDoc 3.
Testing JSDoc 3
About running the self tests included with JSDoc 3.
License
diff --git a/about-migration.html b/about-migration.html new file mode 100644 index 00000000..6c4b4b90 --- /dev/null +++ b/about-migration.html @@ -0,0 +1,318 @@ + + + + + Use JSDoc: Migration guide from JSDoc Toolkit + + + + + + + + + + +
+ @use JSDoc +
+ + + +
+

Migration guide from JSDoc Toolkit

+ + +

Table of Contents

+ + +

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.

+ +

Tags that have different meaning with JSDoc 2

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

Convenient New Features of JSDoc 3

+

JSDoc 3 provides new attractive features that improves your document's quality:

+

Long description:

+

JSDoc 3 has features that import long description instead of just API document created from source files:

+ +
    +

  • README.md importing

    +

    It can import README.md as an index page content.

    +
    • +

  • Tutorial

    +

    It can add long description pages from HTML, Markdown format.

    +
    • +
+ +

Type specification:

+ +

JSDoc 3 starts parsing type specification. It can receive more complex types.

+ +

Description for new types:

+ +

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.

+
    +

  • Callback functions

    +

    JSDoc 3 can define a custom type of callback functions by using the @callback tag.

    +
    • +

  • Enumeration

    +

    Definition of enumeration table in JSDoc 3 (the @enum tag) is easier than JSDoc 2 +(Using @member to each items).

    +
    • +

  • Mix-in

    +

    Mix-in is a popular concept in dynamic languages including JavaScript. + JSDoc 3 can document this idiom by using @mixin and @mixes tags.

    +
    • +

  • Abstract member

    +

    The @abstract tag identifies members that must be implemented +This member should override by child classes.

    +
    • +

  • Readonly

    +

    JSDoc 2 and JSDoc 3 already support the @constant (@const) tag to describe const member. + In addition to that, JSDoc 3 supports the @readonly tag it can use for getters.

    +
    • +

  • Scope tags

    +

    JSDoc adds tags for describing item's scope: @instance (new), @global (new), @inner, @static

    +
    • +
+ +

Module features:

+

JavaScript works on many different environment. Some environment supports module features and other environment +has special objects.

+
    +

  • Modules

    +

    JSDoc 3 supports a module description including CommonJS style module, a node.js style module, RequireJS style modules + See @module, @exports tags documents.

    +
    • +

  • External modules

    +

    JSDoc 3 can describe an external or embedded items by using the @external tag. +The class or type defined in an external module is usable as a base class or a parameter.

    +
    • +
+

Link text font:

+

You don't have to write like <code>{@link Symbol}</code> anymore. JSDoc 3 provides +features to create link with monospace font:

+ +

New tags for more strict, detailed documentation:

+

JSDoc 3 supports new tags to describe more strict, detailed document.

+ + +
+ + + + + + diff --git a/index.html b/index.html index 5354d9fb..714fe945 100644 --- a/index.html +++ b/index.html @@ -219,6 +219,8 @@

Getting Started

Installing plugins and writing your own.
Configuring the markdown plugin
This allows markdown in code comments and offers 2 flavors.
+
Migration Guide from JSDoc Toolkit
+
Difference points between JSDoc Toolkit(JSDoc 2) and JSDoc 3.
Testing JSDoc 3
About running the self tests included with JSDoc 3.
License