From babfab03b77541613c841871cadc5ae0b4da55f1 Mon Sep 17 00:00:00 2001 From: Zearin Date: Thu, 24 May 2018 11:21:56 -0400 Subject: [PATCH 1/5] docs: Format tags & variables instead of quoting --- content/en/about-commandline.md | 4 ++-- content/en/about-configuring-jsdoc.md | 2 +- content/en/about-namepaths.md | 12 +++++----- content/en/about-plugins.md | 18 +++++++------- content/en/tags-abstract.md | 2 +- content/en/tags-alias.md | 28 +++++++++++----------- content/en/tags-author.md | 2 +- content/en/tags-borrows.md | 4 ++-- content/en/tags-callback.md | 6 ++--- content/en/tags-class.md | 2 +- content/en/tags-classdesc.md | 10 ++++---- content/en/tags-constant.md | 10 ++++---- content/en/tags-copyright.md | 4 ++-- content/en/tags-default.md | 4 ++-- content/en/tags-deprecated.md | 4 ++-- content/en/tags-description.md | 8 +++---- content/en/tags-enum.md | 6 ++--- content/en/tags-event.md | 12 +++++----- content/en/tags-example.md | 2 +- content/en/tags-exports.md | 12 +++++----- content/en/tags-file.md | 2 +- content/en/tags-fires.md | 4 ++-- content/en/tags-function.md | 6 ++--- content/en/tags-global.md | 4 ++-- content/en/tags-inner.md | 10 ++++---- content/en/tags-instance.md | 10 ++++---- content/en/tags-kind.md | 34 +++++++++++++-------------- content/en/tags-member.md | 6 ++--- content/en/tags-memberof.md | 28 +++++++++++----------- content/en/tags-mixes.md | 12 +++++----- content/en/tags-mixin.md | 2 +- content/en/tags-module.md | 16 ++++++------- content/en/tags-name.md | 10 ++++---- content/en/tags-namespace.md | 10 ++++---- content/en/tags-property.md | 6 ++--- content/en/tags-readonly.md | 2 +- content/en/tags-requires.md | 6 ++--- content/en/tags-see.md | 2 +- content/en/tags-since.md | 2 +- content/en/tags-static.md | 8 +++---- content/en/tags-summary.md | 2 +- content/en/tags-this.md | 6 ++--- content/en/tags-throws.md | 4 ++-- content/en/tags-todo.md | 4 ++-- content/en/tags-type.md | 6 ++--- content/en/tags-typedef.md | 6 ++--- content/en/tags-variation.md | 14 +++++------ content/en/tags-version.md | 2 +- 48 files changed, 188 insertions(+), 188 deletions(-) diff --git a/content/en/about-commandline.md b/content/en/about-commandline.md index 7c64f60c..2cadab09 100644 --- a/content/en/about-commandline.md +++ b/content/en/about-commandline.md @@ -11,8 +11,8 @@ At its most basic level, JSDoc is used like so: where `...` are paths to other files to generate documentation for. -Additionally, one may provide the path to a [Markdown file][md-file] (ending in ".md") or a file -named "README", and this will be added to the documentation on the front page. See [these +Additionally, one may provide the path to a [Markdown file][md-file] (ending in `.md`) or a file +named `README`, and this will be added to the documentation on the front page. See [these instructions][including-readme]. JSDoc supports a number of command-line options, many of which have both long and short forms. diff --git a/content/en/about-configuring-jsdoc.md b/content/en/about-configuring-jsdoc.md index b2e195c5..a88b9f9f 100644 --- a/content/en/about-configuring-jsdoc.md +++ b/content/en/about-configuring-jsdoc.md @@ -177,7 +177,7 @@ use the [`-r` command-line option][about-commandline] to recurse into subdirecto this array may include subdirectories of the paths in `source.include`. + `source.includePattern`: An optional string, interpreted as a regular expression. If present, all filenames must match this regular expression to be processed by JSDoc. By default, this option is -set to ".+\.js(doc|x)?$", meaning that only files with the extensions `.js`, `.jsdoc`, and +set to `.+\.js(doc|x)?$`, meaning that only files with the extensions `.js`, `.jsdoc`, and `.jsx` will be processed. + `source.excludePattern`: An optional string, interpreted as a regular expression. If present, any file matching this regular expression will be ignored. By default, this option is set so that files diff --git a/content/en/about-namepaths.md b/content/en/about-namepaths.md index d42b6ade..2402e5c7 100644 --- a/content/en/about-namepaths.md +++ b/content/en/about-namepaths.md @@ -21,7 +21,7 @@ MyConstructor~innerMember // note that JSDoc 2 uses a dash ``` {% endexample %} -The example below shows: an _instance_ method named "say," an _inner_ function also named "say," and a _static_ method also named "say." These are three distinct methods that all exist independently of one another. +The example below shows: an _instance_ method named `say`, an _inner_ function also named `say`, and a _static_ method also named `say`. These are three distinct methods that all exist independently of one another. {% example "Use a documentation tag to describe your code." %} @@ -58,7 +58,7 @@ Person~say // the inner method named "say." ``` {% endexample %} -You might wonder why there is a syntax to refer to an inner method when that method isn't directly accessible from outside the function it is defined in. While that is true, and thus the "~" syntax is rarely used, it _is_ possible to return a reference to an inner method from another method inside that container, so it is possible that some object elsewhere in your code might borrow an inner method. +You might wonder why there is a syntax to refer to an inner method when that method isn't directly accessible from outside the function it is defined in. While that is true, and thus the `~` syntax is rarely used, it _is_ possible to return a reference to an inner method from another method inside that container, so it is possible that some object elsewhere in your code might borrow an inner method. Note that if a constructor has an instance member that is also a constructor, you can simply chain the namepaths together to form a longer namepath: @@ -81,7 +81,7 @@ i.consider(); ``` {% endexample %} -In this case, to refer to the method named "consider," you would use the following namepath: +In this case, to refer to the method named `consider`, you would use the following namepath: `Person#Idea#consider` @@ -102,7 +102,7 @@ This chaining can be used with any combination of the connecting symbols: `# . ~ ``` {% endexample %} -There are some special cases with namepaths: [@module][module-tag] names are prefixed by "module:", [@external][external-tag] names are prefixed by "external:", and [@event][event-tag] names are prefixed by "event:". +There are some special cases with namepaths: [`@module`][module-tag] names are prefixed by `module:`, [`@external`][external-tag] names are prefixed by `external:`, and [`@event`][event-tag] names are prefixed by `event:`. {% example "Namepaths of objects with special characters in the name." %} @@ -136,8 +136,8 @@ var chat = { {% endexample %} Above is an example of a namespace with "unusual" characters in its member names (the hash character, dashes, even quotes). -To refer to these you just need quote the names: chat."#channel", chat."#channel"."op:announce-motd", and so on. -Internal quotes in names should be escaped with backslashes: chat."#channel"."say-\"hello\"". +To refer to these you just need quote the names: `chat."#channel"`, `chat."#channel"."op:announce-motd"`, and so on. +Internal quotes in names should be escaped with backslashes: `chat."#channel"."say-\"hello\""`. [event-tag]: tags-event.html [external-tag]: tags-external.html diff --git a/content/en/about-plugins.md b/content/en/about-plugins.md index 20723f7c..0f5fc102 100644 --- a/content/en/about-plugins.md +++ b/content/en/about-plugins.md @@ -63,7 +63,7 @@ An event-handler plugin can stop later plugins from running by setting a `stopPr on the event object (`e.stopPropagation = true`). A plugin can stop the event from firing by setting a `preventDefault` property (`e.preventDefault = true`). -#### Event: parseBegin +#### Event: `parseBegin` The `parseBegin` event is fired before JSDoc starts loading and parsing the source files. Your plugin can control which files JSDoc will parse by modifying the event's contents. @@ -74,7 +74,7 @@ The event object contains the following properties: + `sourcefiles`: An array of paths to source files that will be parsed. -#### Event: fileBegin +#### Event: `fileBegin` The `fileBegin` event is fired when the parser is about to parse a file. Your plugin can use this event to trigger per-file initialization if necessary. @@ -83,7 +83,7 @@ The event object contains the following properties: + `filename`: The name of the file. -#### Event: beforeParse +#### Event: `beforeParse` The `beforeParse` event is fired before parsing has begun. Plugins can use this method to modify the source code that will be parsed. For instance, your plugin could add a JSDoc comment, or it could @@ -118,7 +118,7 @@ exports.handlers = { ``` {% endexample %} -#### Event: jsdocCommentFound +#### Event: `jsdocCommentFound` The `jsdocCommentFound` event is fired whenever a JSDoc comment is found. The comment may or may not be associated with any code. You might use this event to modify the contents of a comment before it @@ -131,7 +131,7 @@ The event object contains the following properties: + `lineno`: The line number on which the comment was found. + `columnno`: The column number on which the comment was found. Available in JSDoc 3.5.0 and later. -#### Event: symbolFound +#### Event: `symbolFound` The `symbolFound` event is fired when the parser comes across a symbol in the code that may need to be documented. For example, the parser fires a `symbolFound` event for each variable, function, and @@ -153,7 +153,7 @@ properties depending on the symbol. [node-visitors]: #node-visitors -#### Event: newDoclet +#### Event: `newDoclet` The `newDoclet` event is the highest-level event. It is fired when a new doclet has been created. This means that a JSDoc comment or a symbol has been processed, and the actual doclet that will be @@ -206,7 +206,7 @@ exports.handlers = { [about-commandline]: about-commandline.html -#### Event: fileComplete +#### Event: `fileComplete` The `fileComplete` event is fired when the parser has finished parsing a file. Your plugin could use this event to trigger per-file cleanup. @@ -216,7 +216,7 @@ The event object contains the following properties: + `filename`: The name of the file. + `source`: The contents of the file. -#### Event: parseComplete +#### Event: `parseComplete` The `parseComplete` event is fired after JSDoc has parsed all of the specified source files. @@ -230,7 +230,7 @@ about the properties that each doclet can contain. Available in JSDoc 3.2.1 and [newdoclet-event]: #event-newdoclet -#### Event: processingComplete +#### Event: `processingComplete` The `processingComplete` event is fired after JSDoc updates the parse results to reflect inherited and borrowed symbols. diff --git a/content/en/tags-abstract.md b/content/en/tags-abstract.md index e6ca5064..d27235b0 100644 --- a/content/en/tags-abstract.md +++ b/content/en/tags-abstract.md @@ -7,7 +7,7 @@ synonyms: ## Overview -The @abstract tag identifies members that must be implemented (or overridden) by objects that +The `@abstract` tag identifies members that must be implemented (or overridden) by objects that inherit the member. ## Example diff --git a/content/en/tags-alias.md b/content/en/tags-alias.md index fee597f5..bf7898ba 100644 --- a/content/en/tags-alias.md +++ b/content/en/tags-alias.md @@ -13,12 +13,12 @@ related: ## Overview -The @alias tag causes JSDoc to treat all references to a member as if the member had a different +The `@alias` tag causes JSDoc to treat all references to a member as if the member had a different name. This tag is especially useful if you define a class within an inner function; in this case, -you can use the @alias tag to tell JSDoc how the class is exposed in your app. +you can use the `@alias` tag to tell JSDoc how the class is exposed in your app. -While the @alias tag may sound similar to the @name tag, these tags behave very differently. The -@name tag tells JSDoc to ignore any code associated with the comment. For example, when JSDoc +While the `@alias` tag may sound similar to the `@name` tag, these tags behave very differently. The +`@name` tag tells JSDoc to ignore any code associated with the comment. For example, when JSDoc processes the following code, it ignores the fact that the comment for `bar` is attached to a function: @@ -30,7 +30,7 @@ function: function foo() {} ``` -The @alias tag tells JSDoc to pretend that Member A is actually named Member B. For example, when +The `@alias` tag tells JSDoc to pretend that Member A is actually named Member B. For example, when JSDoc processes the following code, it recognizes that `foo` is a function, then renames `foo` to `bar` in the documentation: @@ -48,12 +48,12 @@ function foo() {} ## Examples Suppose you are using a class framework that expects you to pass in a constructor function when you -define a class. You can use the @alias tag to tell JSDoc how the class will be exposed in your app. +define a class. You can use the `@alias` tag to tell JSDoc how the class will be exposed in your app. -In the following example, the @alias tag tells JSDoc to treat the anonymous function as if it were -the constructor for the class "trackr.CookieManager". Within the function, JSDoc interprets the -`this` keyword relative to trackr.CookieManager, so the "value" method has the namepath -"trackr.CookieManager#value". +In the following example, the `@alias` tag tells JSDoc to treat the anonymous function as if it were +the constructor for the class `trackr.CookieManager`. Within the function, JSDoc interprets the +`this` keyword relative to `trackr.CookieManager`, so the `value` method has the namepath +`trackr.CookieManager#value`. {% example "Using @alias with an anonymous constructor function" %} @@ -74,8 +74,8 @@ Klass('trackr.CookieManager', ``` {% endexample %} -You can also use the @alias tag with members that are created within an immediately invoked function -expression (IIFE). The @alias tag tells JSDoc that these members are exposed outside of the IIFE's +You can also use the `@alias` tag with members that are created within an immediately invoked function +expression (IIFE). The `@alias` tag tells JSDoc that these members are exposed outside of the IIFE's scope. {% example "Using @alias for static members of a namespace" %} @@ -99,8 +99,8 @@ var Apple = {}; ``` {% endexample %} -For members that are defined within an object literal, you can use the @alias tag as an alternative -to the [@lends][lends-tag] tag. +For members that are defined within an object literal, you can use the `@alias` tag as an alternative +to the [`@lends`][lends-tag] tag. {% example "Using @alias for an object literal" %} diff --git a/content/en/tags-author.md b/content/en/tags-author.md index 91d7c8b1..f6c7e2b1 100644 --- a/content/en/tags-author.md +++ b/content/en/tags-author.md @@ -13,7 +13,7 @@ related: ## Overview -The @author tag identifies the author of an item. In JSDoc 3.2 and later, if the author's name is +The `@author` tag identifies the author of an item. In JSDoc 3.2 and later, if the author's name is followed by an email address enclosed in angle brackets, the default template will convert the email address to a `mailto:` link. diff --git a/content/en/tags-borrows.md b/content/en/tags-borrows.md index dd25fe0d..0018b1dc 100644 --- a/content/en/tags-borrows.md +++ b/content/en/tags-borrows.md @@ -10,7 +10,7 @@ description: This object uses something from another object. ## Overview -The @borrows tag allows you to add documentation for another symbol to your documentation. +The `@borrows` tag allows you to add documentation for another symbol to your documentation. This tag would be useful if you had more than one way to reference a function, but you didn't want to duplicate the same documentation in two places. @@ -18,7 +18,7 @@ to duplicate the same documentation in two places. ## Examples -In this example there exists documentation for the "trstr" function, but "util.trim" is just a +In this example there exists documentation for the `trstr` function, but `util.trim` is just a reference to that same function by a different name. {% example "Duplicate the documentation for trstr as util.trim" %} diff --git a/content/en/tags-callback.md b/content/en/tags-callback.md index 74c24a9e..2d59c071 100644 --- a/content/en/tags-callback.md +++ b/content/en/tags-callback.md @@ -13,12 +13,12 @@ related: ## Overview -The @callback tag provides information about a callback function that can be passed to other +The `@callback` tag provides information about a callback function that can be passed to other functions, including the callback's parameters and return value. You can include any of the tags -that you can provide for a @method. +that you can provide for a `@method`. Once you define a callback, you can use it in the same way as a custom type defined with the -@typedef tag. In particular, you can use the callback's name as a type name. This allows you to +`@typedef` tag. In particular, you can use the callback's name as a type name. This allows you to indicate that a function parameter should contain a certain type of callback. If you want a callback to be displayed with the type definitions for a specific class, you can give diff --git a/content/en/tags-class.md b/content/en/tags-class.md index 7899720e..4d524792 100644 --- a/content/en/tags-class.md +++ b/content/en/tags-class.md @@ -14,7 +14,7 @@ related: ## Overview -The @class tag marks a function as being a constructor, meant to be called with the new +The `@class` tag marks a function as being a constructor, meant to be called with the `new` keyword to return an instance. diff --git a/content/en/tags-classdesc.md b/content/en/tags-classdesc.md index 2cd74d69..f461388f 100644 --- a/content/en/tags-classdesc.md +++ b/content/en/tags-classdesc.md @@ -13,13 +13,13 @@ related: ## Overview -The @classdesc tag is used to provide a description for a class, separate from the constructor -function's description. Use the @classdesc tag in combination with the [@class (or @constructor) +The `@classdesc` tag is used to provide a description for a class, separate from the constructor +function's description. Use the `@classdesc` tag in combination with the [`@class` (or `@constructor`) tag][class-tag]. -The functionality of the @classdesc tag in JSDoc 3 duplicates that of the @class in previous -versions. As of version 3, the syntax and functionality of the @class tag now exactly matches the -@constructor tag, and the @classdesc tag more explicitly communicates its purpose: to document a +The functionality of the `@classdesc` tag in JSDoc 3 duplicates that of the `@class` in previous +versions. As of version 3, the syntax and functionality of the `@class` tag now exactly matches the +`@constructor` tag, and the `@classdesc` tag more explicitly communicates its purpose: to document a class's description. [class-tag]: tags-class.html diff --git a/content/en/tags-constant.md b/content/en/tags-constant.md index 2dbed596..3a3af0d4 100644 --- a/content/en/tags-constant.md +++ b/content/en/tags-constant.md @@ -15,14 +15,14 @@ related: ## Overview -The @constant tag is used to mark the documentation as belonging to a symbol that is a constant. +The `@constant` tag is used to mark the documentation as belonging to a symbol that is a constant. ## Examples In this example we are documenting a string constant. Note that although the code is using the `const` keyword, this is not required by JSDoc. If your JavaScript host environment doesn't yet -support constant declarations, the @const documentation can just as effectively be used on `var` +support constant declarations, the `@const` documentation can just as effectively be used on `var` declarations. {% example "A string constant representing the color red" %} @@ -39,6 +39,6 @@ var ONE = 1; ``` {% endexample %} -Note that the example provides the type in a @type tag. This is optional. Also the optional -@default tag is used here too, this will automatically add whatever the assigned value is (for -example 'FF0000') to the documentation. +Note that the example provides the type in a `@type` tag. This is optional. Also the optional +`@default` tag is used here too, this will automatically add whatever the assigned value is (for +example `'FF0000'`) to the documentation. diff --git a/content/en/tags-copyright.md b/content/en/tags-copyright.md index c9323d7a..2a822a37 100644 --- a/content/en/tags-copyright.md +++ b/content/en/tags-copyright.md @@ -12,8 +12,8 @@ related: ## Overview -The @copyright tag is used to document copyright information in a file overview comment. Use this -tag in combination with the [@file tag][file-tag]. +The `@copyright` tag is used to document copyright information in a file overview comment. Use this +tag in combination with the [`@file` tag][file-tag]. [file-tag]: tags-file.html diff --git a/content/en/tags-default.md b/content/en/tags-default.md index e23b343d..e9bd6ec7 100644 --- a/content/en/tags-default.md +++ b/content/en/tags-default.md @@ -12,7 +12,7 @@ synonyms: ## Overview -The @default tag allows you to document the assigned value of a symbol. You can supply this tag with +The `@default` tag allows you to document the assigned value of a symbol. You can supply this tag with a value yourself or you can allow JSDoc to automatically document the value from the source code -- only possible when the documented symbol is being assigned a single, simple value that is either: a string, a number, a boolean or null. @@ -21,7 +21,7 @@ string, a number, a boolean or null. ## Examples In this example a constant is documented. The value of the constant is `0xff0000`. By adding the -@default tag this value is automatically added to the documentation. +`@default` tag this value is automatically added to the documentation. {% example "Document the number value of a constant" %} diff --git a/content/en/tags-deprecated.md b/content/en/tags-deprecated.md index d5756530..a8cf8a7e 100644 --- a/content/en/tags-deprecated.md +++ b/content/en/tags-deprecated.md @@ -10,11 +10,11 @@ description: Document that this is no longer the preferred way. ## Overview -The @deprecated tag marks a symbol in your code as being deprecated. +The `@deprecated` tag marks a symbol in your code as being deprecated. ## Examples -You can use the @deprecated tag by itself, or include some text that describes more about the +You can use the `@deprecated` tag by itself, or include some text that describes more about the deprecation. {% example "Document that the old function has been deprecated since version 2.0" %} diff --git a/content/en/tags-description.md b/content/en/tags-description.md index 683a1f2c..553d8bc3 100644 --- a/content/en/tags-description.md +++ b/content/en/tags-description.md @@ -15,7 +15,7 @@ related: ## Overview -The @description tag allows you to provide a general description of the symbol you are documenting. +The `@description` tag allows you to provide a general description of the symbol you are documenting. The description may include HTML markup. It may also include Markdown formatting if the [Markdown plugin][markdown-plugin] is enabled. @@ -25,7 +25,7 @@ The description may include HTML markup. It may also include Markdown formatting ## Examples If you describe a symbol at the very beginning of a JSDoc comment, before using any block tags, you -may omit the @description tag. +may omit the `@description` tag. {% example "Describing a symbol without the @description tag" %} @@ -42,7 +42,7 @@ function add(a, b) { ``` {% endexample %} -By using the @description tag, you can place the description anywhere in the JSDoc comment. +By using the `@description` tag, you can place the description anywhere in the JSDoc comment. {% example "Describing a symbol with the @description tag" %} @@ -59,4 +59,4 @@ function add(a, b) { ``` {% endexample %} -If there's both a description at the beginning of a JSDoc comment and a description provided with the @description tag, the description specified with the @description will override the description at the beginning of the comment. +If there's both a description at the beginning of a JSDoc comment and a description provided with the `@description` tag, the description specified with the `@description` will override the description at the beginning of the comment. diff --git a/content/en/tags-enum.md b/content/en/tags-enum.md index c066904e..84d380c0 100644 --- a/content/en/tags-enum.md +++ b/content/en/tags-enum.md @@ -12,18 +12,18 @@ related: ## Overview -The @enum tag documents a collection of static properties whose values are all of the same type. +The `@enum` tag documents a collection of static properties whose values are all of the same type. An enum is similar a collection of properties, except that an enum is documented in its own doc comment, whereas properties are documented within the doc comment of their container. Often this tag -is used with @readonly, as an enum typically represents a collection of constants. +is used with `@readonly`, as an enum typically represents a collection of constants. ## Examples This shows how to document an object that represents a value with three possible states. Note that the enum members can have optional descriptions added if you wish. Also you can override the type, -as is shown with "MAYBE" -- by default enum members will be documented with the same type as the +as is shown with `MAYBE` -- by default enum members will be documented with the same type as the enum itself. {% example "A numeric enum, representing three states" %} diff --git a/content/en/tags-event.md b/content/en/tags-event.md index b202f1c6..745cb180 100644 --- a/content/en/tags-event.md +++ b/content/en/tags-event.md @@ -13,19 +13,19 @@ related: ## Overview -The @event tag allows you to document an event that can be fired. A typical event is represented by +The `@event` tag allows you to document an event that can be fired. A typical event is represented by an object with a defined set of properties. -Once you have used the @event tag to define a specific type of event, you can use the @fires tag to -indicate that a method can fire that event. You can also use the @listens tag to indicate that a +Once you have used the `@event` tag to define a specific type of event, you can use the `@fires` tag to +indicate that a method can fire that event. You can also use the `@listens` tag to indicate that a symbol listens for the event. JSDoc automatically prepends the namespace `event:` to each event's name. In general, you must -include this namespace when you link to the event in another doclet. (The @fires tag is a notable +include this namespace when you link to the event in another doclet. (The `@fires` tag is a notable exception; it allows you to omit the namespace.) -**Note**: JSDoc 3 uses @event doclets to document the content of an event. In contrast, JSDoc -Toolkit 2 used @event doclets to identify a function that can be fired when an event of the same +**Note**: JSDoc 3 uses `@event` doclets to document the content of an event. In contrast, JSDoc +Toolkit 2 used `@event` doclets to identify a function that can be fired when an event of the same name occurs. diff --git a/content/en/tags-example.md b/content/en/tags-example.md index fd7e76a5..a877bcad 100644 --- a/content/en/tags-example.md +++ b/content/en/tags-example.md @@ -32,7 +32,7 @@ globalNS.method1 = function (a, b) { ``` {% endexample %} -Examples can also be captioned using `` after the @example tag. +Examples can also be captioned using `` after the `@example` tag. {% example "Documenting examples with a caption" %} diff --git a/content/en/tags-exports.md b/content/en/tags-exports.md index c13b4679..14c9cca2 100644 --- a/content/en/tags-exports.md +++ b/content/en/tags-exports.md @@ -17,15 +17,15 @@ must omit this prefix. ## Overview -Use the @exports tag when documenting JavaScript modules that export anything other than the -"exports" object or the "module.exports" property. +Use the `@exports` tag when documenting JavaScript modules that export anything other than the +`exports` object or the `module.exports` property. ## Examples -In modules where you are using the special "exports" object, the @exports tag is never needed. JSDoc +In modules where you are using the special `exports` object, the `@exports` tag is never needed. JSDoc automatically recognizes that this object's members are being exported. Similarly, JSDoc -automatically recognizes the special "module.exports" property in Node.js modules. +automatically recognizes the special `module.exports` property in Node.js modules. {% example "CommonJS module" %} @@ -105,8 +105,8 @@ define(function() { ``` {% endexample %} -If your module exports an object named anything other than "exports" or "module.exports", use the -@exports tag to indicate what is being exported. +If your module exports an object named anything other than `exports` or `module.exports`, use the +`@exports` tag to indicate what is being exported. {% example "AMD module that exports an object" %} diff --git a/content/en/tags-file.md b/content/en/tags-file.md index bdfad692..1c6ff305 100644 --- a/content/en/tags-file.md +++ b/content/en/tags-file.md @@ -11,7 +11,7 @@ related: ## Overview -The @file tag provides a description for a file. Use the tag in a JSDoc comment at the beginning of +The `@file` tag provides a description for a file. Use the tag in a JSDoc comment at the beginning of the file. diff --git a/content/en/tags-fires.md b/content/en/tags-fires.md index af190395..90e693e1 100644 --- a/content/en/tags-fires.md +++ b/content/en/tags-fires.md @@ -15,8 +15,8 @@ related: ## Overview -The @fires tag indicates that a method can fire a specified type of event when it is called. Use the -[@event tag][event-tag] to document the event's content. +The `@fires` tag indicates that a method can fire a specified type of event when it is called. Use the +[`@event` tag][event-tag] to document the event's content. [event-tag]: tags-event.html diff --git a/content/en/tags-function.md b/content/en/tags-function.md index 0231186e..aaf1dc15 100644 --- a/content/en/tags-function.md +++ b/content/en/tags-function.md @@ -14,7 +14,7 @@ synonyms: ## Overview This marks an object as being a function, even though it may not appear to be one to the parser. It -sets the doclet's [@kind][kind-tag] to 'function'. +sets the doclet's [`@kind`][kind-tag] to `function`. [kind-tag]: tags-kind.html @@ -29,8 +29,8 @@ var paginate = paginateFactory(pages); ``` {% endexample %} -Without the @function tag, the `paginate` object would be documented as a generic object (a -[@member][member-tag]), because it isn't possible to tell from examining the line of code what type +Without the `@function` tag, the `paginate` object would be documented as a generic object (a +[`@member`][member-tag]), because it isn't possible to tell from examining the line of code what type of value `paginate` will hold when it is run. {% example "Using @function with a name." %} diff --git a/content/en/tags-global.md b/content/en/tags-global.md index e4c4bdec..600c65e6 100644 --- a/content/en/tags-global.md +++ b/content/en/tags-global.md @@ -10,14 +10,14 @@ related: ## Overview -The @global tag specifies that a symbol should appear in the documentation as a _global_ symbol. +The `@global` tag specifies that a symbol should appear in the documentation as a _global_ symbol. JSDoc ignores the symbol's actual scope within the source file. This tag is especially useful for symbols that are defined locally, then assigned to a global symbol. ## Examples -Use the @global tag to specify that a symbol should be documented as global. +Use the `@global` tag to specify that a symbol should be documented as global. {% example "Document an inner variable as a global" %} diff --git a/content/en/tags-inner.md b/content/en/tags-inner.md index ee982161..44f03b4f 100644 --- a/content/en/tags-inner.md +++ b/content/en/tags-inner.md @@ -9,10 +9,10 @@ related: ## Overview -Using the @inner tag will mark a symbol as an inner member of its parent symbol. This means it can -be referred to by "Parent~Child". +Using the `@inner` tag will mark a symbol as an inner member of its parent symbol. This means it can +be referred to by `Parent~Child`. -Using @inner will override a doclet's default scope (unless it is in the global scope, in which case +Using `@inner` will override a doclet's default scope (unless it is in the global scope, in which case it will remain global). @@ -31,8 +31,8 @@ it will remain global). ``` {% endexample %} -Note that in the above we could have used "@function MyNamespace~myFunction" instead of the -@memberof and @inner tags. +Note that in the above we could have used `@function MyNamespace~myFunction` instead of the +`@memberof` and `@inner` tags. {% example "Using @inner" %} diff --git a/content/en/tags-instance.md b/content/en/tags-instance.md index 24a4e186..b3e81a9a 100644 --- a/content/en/tags-instance.md +++ b/content/en/tags-instance.md @@ -9,16 +9,16 @@ related: ## Overview -Using the @instance tag will mark a symbol as an instance member of its parent symbol. This means it -can be referred to by "Parent#Child". +Using the `@instance` tag will mark a symbol as an instance member of its parent symbol. This means it +can be referred to by `Parent#Child`. -Using @instance will override a doclet's default scope (unless it is in the global scope, in which +Using `@instance` will override a doclet's default scope (unless it is in the global scope, in which case it will remain global). ## Examples -The following example is a longhand way of writing "@function MyNamespace#myFunction": +The following example is a longhand way of writing `@function MyNamespace#myFunction`: {% example "Using @instance to make a virtual doclet an instance member" %} @@ -33,7 +33,7 @@ The following example is a longhand way of writing "@function MyNamespace#myFunc ``` {% endexample %} -More usefully, you can use the @instance tag to override the scope that JSDoc infers. For example, +More usefully, you can use the `@instance` tag to override the scope that JSDoc infers. For example, you can indicate that a static member is used as an instance member: {% example "Using @instance to identify an instance member" %} diff --git a/content/en/tags-kind.md b/content/en/tags-kind.md index 52a917d7..91ea7541 100644 --- a/content/en/tags-kind.md +++ b/content/en/tags-kind.md @@ -11,27 +11,27 @@ related: where `` is one of: -+ class -+ constant -+ event -+ external -+ file -+ function -+ member -+ mixin -+ module -+ namespace -+ typedef ++ `class` ++ `constant` ++ `event` ++ `external` ++ `file` ++ `function` ++ `member` ++ `mixin` ++ `module` ++ `namespace` ++ `typedef` ## Overview -The @kind tag is used to document what _kind_ of symbol is being documented (for example, a class or +The `@kind` tag is used to document what _kind_ of symbol is being documented (for example, a class or a module). The _kind_ of symbol differs from a symbol's _type_ (for example, string or boolean). -Usually you do not need the @kind tag, because the symbol's kind is determined by other tags in the -doclet. For example, using the @class tag automatically implies "@kind class", and using the -@namespace tag implies "@kind namespace". +Usually you do not need the `@kind` tag, because the symbol's kind is determined by other tags in the +doclet. For example, using the `@class` tag automatically implies `@kind class`, and using the +`@namespace` tag implies `@kind namespace`. ## Examples @@ -55,8 +55,8 @@ const asdf = 1; ``` {% endexample %} -In the case of tags with conflicting kinds (for example, using both @module, which sets the kind to -"module", and "@kind constant" which sets the kind to "constant"), the last tag determines the kind. +In the case of tags with conflicting kinds (for example, using both `@module`, which sets the kind to +`module`, and `@kind constant` which sets the kind to `constant`), the last tag determines the kind. {% example "Conflicting @kind statements" %} diff --git a/content/en/tags-member.md b/content/en/tags-member.md index 48fabc7c..7ea8faa9 100644 --- a/content/en/tags-member.md +++ b/content/en/tags-member.md @@ -11,8 +11,8 @@ synonyms: ## Overview -The @member tag identifies any member that does not have a more specialized kind, such as "class", -"function", or "constant". A member can optionally have a type as well as a name. +The `@member` tag identifies any member that does not have a more specialized kind, such as `class`, +`function`, or `constant`. A member can optionally have a type as well as a name. ## Examples @@ -28,7 +28,7 @@ function Data() { ``` {% endexample %} -Here is an example of using @var, a synonym of @member, to document a (virtual) variable 'foo'. +Here is an example of using `@var`, a synonym of `@member`, to document a (virtual) variable `foo`. {% example "Using @var to document a virtual member" %} diff --git a/content/en/tags-memberof.md b/content/en/tags-memberof.md index 3a884de2..0ba505bb 100644 --- a/content/en/tags-memberof.md +++ b/content/en/tags-memberof.md @@ -13,13 +13,13 @@ related: ## Overview -The @memberof tag identifies a member symbol that belongs to a parent symbol. +The `@memberof` tag identifies a member symbol that belongs to a parent symbol. -By default, the @memberof tag documents member symbols as static members. For inner and instance -members, you can use scoping punctuation after the namepath, or you can add the [@inner][inner-tag] -or [@instance][instance-tag] tag. +By default, the `@memberof` tag documents member symbols as static members. For inner and instance +members, you can use scoping punctuation after the namepath, or you can add the [`@inner`][inner-tag] +or [`@instance`][instance-tag] tag. -The "forced" @memberof tag, @memberof!, forces the object to be documented as belonging to a specific +The "forced" `@memberof` tag, `@memberof!`, forces the object to be documented as belonging to a specific parent even if it appears to have a different parent. [inner-tag]: tags-inner.html @@ -30,7 +30,7 @@ parent even if it appears to have a different parent. In the following example, the `hammer` function would normally be documented as a global function. That's because, in fact, it is a global function, but it is also a member of the `Tools` namespace, -and that's how you wish to document it. The solution is to add a @memberof tag: +and that's how you wish to document it. The solution is to add a `@memberof` tag: {% example "Using @memberof" %} @@ -46,8 +46,8 @@ Tools.hammer = hammer; ``` {% endexample %} -For instance members of a class, use the syntax "@memberof ClassName.prototype" or "@memberof -ClassName#". Alternatively, you can combine "@memberof ClassName" with the "@instance" tag. +For instance members of a class, use the syntax `@memberof ClassName.prototype` or +`@memberof ClassName#`. Alternatively, you can combine `@memberof ClassName` with the `@instance` tag. {% example "Using @memberof with a class prototype" %} @@ -85,13 +85,13 @@ create( ``` {% endexample %} -The following example uses the forced @memberof tag, "@memberof!", to document a property of an -object (Data#point) that is an instance member of a class (Data). +The following example uses the forced `@memberof` tag, `@memberof!`, to document a property of an +object (`Data#point`) that is an instance member of a class (`Data`). -When you use the @property tag to document a property, you cannot link to the property using its -longname. We can force the property to be linkable by using "@alias" and "@memberof!" to tell JSDoc -that Data#point.y should be documented as a member "point.y" of "Data#", rather than a member "y" of -"point" of "Data#". +When you use the `@property` tag to document a property, you cannot link to the property using its +longname. We can force the property to be linkable by using `@alias` and `@memberof!` to tell JSDoc +that `Data#point.y` should be documented as a member `point.y` of `Data#`, rather than a member `y` of +`point` of `Data#`. {% example "Using @memberof! for object properties" %} diff --git a/content/en/tags-mixes.md b/content/en/tags-mixes.md index a2023abc..d6f51f8c 100644 --- a/content/en/tags-mixes.md +++ b/content/en/tags-mixes.md @@ -14,15 +14,15 @@ related: ## Overview -The @mixes tag indicates that the current object mixes in all the members from `OtherObjectPath`, -which is a [@mixin][mixin-tag]. +The `@mixes` tag indicates that the current object mixes in all the members from `OtherObjectPath`, +which is a [`@mixin`][mixin-tag]. [mixin-tag]: tags-mixin.html ## Examples -To start, we document a mixin with the [@mixin][mixin-tag] tag: +To start, we document a mixin with the [`@mixin`][mixin-tag] tag: {% example "Example of a @mixin" %} @@ -55,9 +55,9 @@ var Eventful = { ``` {% endexample %} -Now we add a FormButton class and call a "mix" function that mixes all of the Eventful functions -into FormButton, so that FormButton can also fire events and have listeners. We use the @mixes tag -to indicate that FormButton mixes the Eventful functions. +Now we add a `FormButton` class and call a `mix` function that mixes all of the Eventful functions +into `FormButton`, so that `FormButton` can also fire events and have listeners. We use the `@mixes` tag +to indicate that `FormButton` mixes the `Eventful` functions. {% example "Using the @mixes tag" %} diff --git a/content/en/tags-mixin.md b/content/en/tags-mixin.md index 4ee53d16..3a0fda21 100644 --- a/content/en/tags-mixin.md +++ b/content/en/tags-mixin.md @@ -15,7 +15,7 @@ related: ## Overview A mixin provides functionality that is intended to be added to other objects. If desired, you can -use the @mixin tag to indicate that an object is a mixin. You can then add the @mixes tag to objects +use the `@mixin` tag to indicate that an object is a mixin. You can then add the `@mixes` tag to objects that use the mixin. diff --git a/content/en/tags-module.md b/content/en/tags-module.md index 8df9576c..e61278d8 100644 --- a/content/en/tags-module.md +++ b/content/en/tags-module.md @@ -19,16 +19,16 @@ Note: If you provide a type, you _must_ also provide a name. ## Overview -The @module tag marks the current file as being its own module. All symbols in the file are assumed +The `@module` tag marks the current file as being its own module. All symbols in the file are assumed to be members of the module unless documented otherwise. -Link to a module (e.g. within a [@link][link-tag] or [@see][see-tag] tag) using "module:moduleName". -For example, "@module foo/bar" can be linked to using "{@link module:foo/bar}". +Link to a module (e.g. within a [`@link`][link-tag] or [`@see`][see-tag] tag) using `module:moduleName`. +For example, `@module foo/bar` can be linked to using `{@link module:foo/bar}`. If the module name is not provided, it is derived from the module's path and filename. For example, suppose I have a file `test.js`, located in the `src` directory, that contains the block comment `/** @module */`. Here are some scenarios for running JSDoc and the resulting module names for -test.js: +`test.js`: {% example "Derived module names if none is provided." %} @@ -68,8 +68,8 @@ var bar = function() {}; When an exported symbol is defined as a member of `module.exports`, `exports`, or `this`, JSDoc infers that the symbol is a static member of the module. -In the following example, the Book class is documented as a static member, "module:bookshelf.Book", -with one instance member, "module:bookshelf.Book#title". +In the following example, the `Book` class is documented as a static member, `module:bookshelf.Book`, +with one instance member, `module:bookshelf.Book#title`. {% example "Defining exported symbols as a member of 'this'" %} @@ -83,8 +83,8 @@ this.Book = function (title) { ``` {% endexample %} -In the following example, the two functions have the namepaths "module:color/mixer.blend" and -"module:color/mixer.darken". +In the following example, the two functions have the namepaths `module:color/mixer.blend` and +`module:color/mixer.darken`. {% example "Defining exported symbols as a member of 'module.exports' or 'exports'" %} diff --git a/content/en/tags-name.md b/content/en/tags-name.md index f7aa1118..39c04821 100644 --- a/content/en/tags-name.md +++ b/content/en/tags-name.md @@ -12,17 +12,17 @@ related: ## Overview -The @name tag forces JSDoc to associate the remainder of the JSDoc comment with the given name, +The `@name` tag forces JSDoc to associate the remainder of the JSDoc comment with the given name, ignoring all surrounding code. This tag is best used in "virtual comments" for symbols that are not readily visible in the code, such as methods that are generated at runtime. -When you use the @name tag, you must provide additional tags that tell JSDoc what kind of symbol you +When you use the `@name` tag, you must provide additional tags that tell JSDoc what kind of symbol you are documenting; whether the symbol is a member of another symbol; and so on. If you do not provide this information, the symbol will not be documented correctly. -**Warning**: By using the @name tag, you are telling JSDoc to _ignore the surrounding code_ and +**Warning**: By using the `@name` tag, you are telling JSDoc to _ignore the surrounding code_ and treat your documentation comment in isolation. In many cases, it is best to use the -[@alias tag][alias-tag] instead, which changes a symbol's name in the documentation but preserves +[`@alias` tag][alias-tag] instead, which changes a symbol's name in the documentation but preserves other information about the symbol. [alias-tag]: tags-alias.html @@ -30,7 +30,7 @@ other information about the symbol. ## Examples -The following example shows how to use the @name tag to document a function that JSDoc would not +The following example shows how to use the `@name` tag to document a function that JSDoc would not normally recognize. {% example "Using the @name tag" %} diff --git a/content/en/tags-namespace.md b/content/en/tags-namespace.md index 2bacac44..a48bc553 100644 --- a/content/en/tags-namespace.md +++ b/content/en/tags-namespace.md @@ -12,14 +12,14 @@ related: ## Overview -The @namespace tag indicates that an object creates a namespace for its members. You can also write +The `@namespace` tag indicates that an object creates a namespace for its members. You can also write a virtual JSDoc comment that defines a namespace used by your code. If a namespace is defined by a symbol other than an object literal, you can include a type -expression along with the @namespace tag. If the @namespace tag includes a type, it must also +expression along with the `@namespace` tag. If the `@namespace` tag includes a type, it must also include a name. -You may need to document a namespace whose name includes unusual characters, such as "#" or "!". In +You may need to document a namespace whose name includes unusual characters, such as `#` or `!`. In these cases, when you document or link to the namespace, you must add quotation marks around the portion of the namespace that includes unusual characters. See the examples below for details. @@ -58,9 +58,9 @@ var MyNamespace = { ``` {% endexample %} -If a @namespace includes a symbol whose name has unusual characters, you must enclose the symbol's +If a `@namespace` includes a symbol whose name has unusual characters, you must enclose the symbol's name in double quotes. If the symbol's name already contains one or more double quotes, escape the -double quotes with a leading backslash (\\). +double quotes with a leading backslash (`\\`). {% example "Using the @namespace tag with unusual member names" %} diff --git a/content/en/tags-property.md b/content/en/tags-property.md index a14b9984..88b1c012 100644 --- a/content/en/tags-property.md +++ b/content/en/tags-property.md @@ -10,7 +10,7 @@ related: ## Overview -The @property tag is a way to easily document a list of static properties of a class, namespace or +The `@property` tag is a way to easily document a list of static properties of a class, namespace or other object. Normally JSDoc templates would create an entire new page to display information about each level of @@ -19,13 +19,13 @@ including nested properties, all together on the same page. Note that property tags must be used in doc comments for the thing that they are properties of, a namespace or a class for example. This tag is intended for simple collections of static properties, -it does not allow you to provide @examples or similar complex information for each property, just +it does not allow you to provide `@examples` or similar complex information for each property, just the type, name and description. ## Examples -In this example we have a namespace named "config." We want all the information about the defaults +In this example we have a namespace named `config`. We want all the information about the defaults property, including its nested values, to appear on the same page with the documentation for config. {% example "A namespace with defaults and nested default properties" %} diff --git a/content/en/tags-readonly.md b/content/en/tags-readonly.md index e9b1bd63..26c8a088 100644 --- a/content/en/tags-readonly.md +++ b/content/en/tags-readonly.md @@ -5,7 +5,7 @@ description: This symbol is meant to be read-only. ## Overview -The @readonly tag indicates that a symbol is intended to be read-only. Note this is for the purpose +The `@readonly` tag indicates that a symbol is intended to be read-only. Note this is for the purpose of documentation only - JSDoc won't check whether you've _actually_ treated the symbol as read-only in your code. diff --git a/content/en/tags-requires.md b/content/en/tags-requires.md index 11e27fcc..046f5728 100644 --- a/content/en/tags-requires.md +++ b/content/en/tags-requires.md @@ -9,9 +9,9 @@ description: This file requires a JavaScript module. ## Overview -The @requires tag allows you to document that a module is needed to use this code. A JSDoc comment -can have multiple @require tags. The module name can be specified as "moduleName" or -"module:moduleName"; both forms will be interpreted as modules. +The `@requires` tag allows you to document that a module is needed to use this code. A JSDoc comment +can have multiple `@require` tags. The module name can be specified as `moduleName` or +`module:moduleName`; both forms will be interpreted as modules. JSDoc does not attempt to process the module that is being included. If you want the module to be included in the documentation, you must include the module in the list of JavaScript files to diff --git a/content/en/tags-see.md b/content/en/tags-see.md index d8553eb0..c4ccfe2f 100644 --- a/content/en/tags-see.md +++ b/content/en/tags-see.md @@ -13,7 +13,7 @@ related: ## Overview -The @see tag allows you to refer to another symbol or resource that may be related to the one being +The `@see` tag allows you to refer to another symbol or resource that may be related to the one being documented. You can provide either a symbol's namepath or free-form text. If you provide a namepath, JSDoc's default template automatically converts the namepath to a link. diff --git a/content/en/tags-since.md b/content/en/tags-since.md index 5f9ce38c..56d805b0 100644 --- a/content/en/tags-since.md +++ b/content/en/tags-since.md @@ -12,7 +12,7 @@ related: ## Overview -The @since tag indicates that a class, method, or other symbol was added in a specific version. +The `@since` tag indicates that a class, method, or other symbol was added in a specific version. ## Examples diff --git a/content/en/tags-static.md b/content/en/tags-static.md index 087b0e52..9874f72a 100644 --- a/content/en/tags-static.md +++ b/content/en/tags-static.md @@ -9,17 +9,17 @@ related: ## Overview -The @static tag indicates that a symbol is contained within a parent and can be accessed without +The `@static` tag indicates that a symbol is contained within a parent and can be accessed without instantiating the parent. -Using the @static tag will override a symbol's default scope, with one exception: Symbols in global +Using the `@static` tag will override a symbol's default scope, with one exception: Symbols in global scope will remain global. ## Examples -The following example has the same effect as writing "@function MyNamespace.myFunction" and omitting -the @memberof and @static tags: +The following example has the same effect as writing `@function MyNamespace.myFunction` and omitting +the `@memberof` and `@static` tags: {% example "Using @static in a virtual comment" %} diff --git a/content/en/tags-summary.md b/content/en/tags-summary.md index eaa02c54..a5fa0bcb 100644 --- a/content/en/tags-summary.md +++ b/content/en/tags-summary.md @@ -13,7 +13,7 @@ related: ## Overview -The @summary tag is a shorter version of the full description. It can be added to any doclet. +The `@summary` tag is a shorter version of the full description. It can be added to any doclet. ## Examples diff --git a/content/en/tags-this.md b/content/en/tags-this.md index 87a65a57..6edc3297 100644 --- a/content/en/tags-this.md +++ b/content/en/tags-this.md @@ -12,13 +12,13 @@ related: ## Overview -The @this tag indicates what the `this` keyword refers to when used within another symbol. +The `@this` tag indicates what the `this` keyword refers to when used within another symbol. ## Examples -In the following example, the @this tag causes "this.name" to be documented as "Greeter#name" -rather than a global symbol called "name". +In the following example, the `@this` tag causes `this.name` to be documented as `Greeter#name` +rather than a global symbol called `name`. ```js /** @constructor */ diff --git a/content/en/tags-throws.md b/content/en/tags-throws.md index 2f6dd26e..04605092 100644 --- a/content/en/tags-throws.md +++ b/content/en/tags-throws.md @@ -14,8 +14,8 @@ synonyms: ## Overview -The @throws tag allows you to document an error that a function might throw. You can include the -@throws tag more than once in a single JSDoc comment. +The `@throws` tag allows you to document an error that a function might throw. You can include the +`@throws` tag more than once in a single JSDoc comment. ## Examples diff --git a/content/en/tags-todo.md b/content/en/tags-todo.md index 1a376398..79c51786 100644 --- a/content/en/tags-todo.md +++ b/content/en/tags-todo.md @@ -10,8 +10,8 @@ description: Document tasks to be completed. ## Overview -The @todo tag allows you to document tasks to be completed for some part of your code. You can use -the @todo tag more than once in a single JSDoc comment. +The `@todo` tag allows you to document tasks to be completed for some part of your code. You can use +the `@todo` tag more than once in a single JSDoc comment. ## Examples diff --git a/content/en/tags-type.md b/content/en/tags-type.md index 3c6cace4..667670a1 100644 --- a/content/en/tags-type.md +++ b/content/en/tags-type.md @@ -15,9 +15,9 @@ related: ## Overview -The @type tag allows you to provide a type expression identifying the type of value that a symbol +The `@type` tag allows you to provide a type expression identifying the type of value that a symbol may contain, or the type of value returned by a function. You can also include type expressions with -many other JSDoc tags, such as the [@param tag][param-tag]. +many other JSDoc tags, such as the [`@param` tag][param-tag]. A type expression can include the JSDoc namepath to a symbol (for example, `myNamespace.MyClass`); a built-in JavaScript type (for example, `string`); or a combination of these. You can use any @@ -280,7 +280,7 @@ var bar = 1; {% endexample %} In many cases, you can include a type expression as part of another tag, rather than including a -separate @type tag in your JSDoc comment. +separate `@type` tag in your JSDoc comment. {% example "Type expressions can accompany many tags." %} diff --git a/content/en/tags-typedef.md b/content/en/tags-typedef.md index 12dbebc4..39159014 100644 --- a/content/en/tags-typedef.md +++ b/content/en/tags-typedef.md @@ -14,11 +14,11 @@ related: ## Overview -The @typedef tag is useful for documenting custom types, particularly if you wish to refer to them +The `@typedef` tag is useful for documenting custom types, particularly if you wish to refer to them repeatedly. These types can then be used within other tags expecting a type, such as -[@type][type-tag] or [@param][param-tag]. +[`@type`][type-tag] or [`@param`][param-tag]. -Use the [@callback][callback-tag] tag to document the type of callback functions. +Use the [`@callback`][callback-tag] tag to document the type of callback functions. [callback-tag]: tags-callback.html [param-tag]: tags-param.html diff --git a/content/en/tags-variation.md b/content/en/tags-variation.md index abb3b8f2..8bce74ca 100644 --- a/content/en/tags-variation.md +++ b/content/en/tags-variation.md @@ -15,15 +15,15 @@ related: Sometimes your code may include multiple symbols with the same longname. For example, you might have both a global class and a top-level namespace called `Widget`. In cases such as these, what does -"{@link Widget}" or "@memberof Widget" mean? The global namespace, or the global class? +`{@link Widget}` or `@memberof Widget` mean? The global namespace, or the global class? Variations help JSDoc distinguish between different symbols with the same longname. For example, if -"@variation 2" is added to the JSDoc comment for the Widget class, "{@link Widget(2)}" will refer to -the class, and "{@link Widget}" will refer to the namespace. Alternatively, you can include the -variation when you specify the symbol's with tags such as [@alias][alias-tag] or [@name][name-tag] -(for example, "@alias Widget(2)"). +`@variation 2` is added to the JSDoc comment for the Widget class, `{@link Widget(2)}` will refer to +the class, and `{@link Widget}` will refer to the namespace. Alternatively, you can include the +variation when you specify the symbol's with tags such as [`@alias`][alias-tag] or [`@name`][name-tag] +(for example, `@alias Widget(2)`). -You can provide any value with the @variation tag, as long as the combination of the value and the +You can provide any value with the `@variation` tag, as long as the combination of the value and the longname results in a globally unique version of the longname. As a best practice, use a predictable pattern for choosing the values, which will make it easier for you to document your code. @@ -33,7 +33,7 @@ pattern for choosing the values, which will make it easier for you to document y ## Examples -The following example uses the @variation tag to distinguish between the Widget class and the Widget +The following example uses the `@variation` tag to distinguish between the Widget class and the Widget namespace. {% example "Using the @variation tag" %} diff --git a/content/en/tags-version.md b/content/en/tags-version.md index 6a6ddd56..97690848 100644 --- a/content/en/tags-version.md +++ b/content/en/tags-version.md @@ -7,7 +7,7 @@ related: ## Overview -Documents the version of an item. The text following the @version tag will be used to denote the +Documents the version of an item. The text following the `@version` tag will be used to denote the version of the item. From 8aa5358e6a137c1d0648f2a70cc86482ea62dc53 Mon Sep 17 00:00:00 2001 From: Zearin Date: Thu, 24 May 2018 11:44:35 -0400 Subject: [PATCH 2/5] docs: Rebuild HTML --- about-block-inline-tags.html | 12 ++-- about-commandline.html | 73 +++++++++---------------- about-configuring-default-template.html | 3 +- about-configuring-jsdoc.html | 52 ++++++------------ about-getting-started.html | 15 ++--- about-including-package.html | 9 +-- about-including-readme.html | 9 +-- about-license-jsdoc3.html | 3 +- about-namepaths.html | 43 ++++++--------- about-plugins.html | 48 +++++++--------- about-tutorials.html | 24 +++----- howto-amd-modules.html | 18 ++---- howto-commonjs-modules.html | 37 +++++-------- howto-es2015-classes.html | 12 ++-- howto-es2015-modules.html | 6 +- index.html | 3 +- plugins-markdown.html | 33 ++++------- tags-abstract.html | 8 +-- tags-access.html | 9 +-- tags-alias.html | 45 +++++++-------- tags-async.html | 9 +-- tags-augments.html | 12 ++-- tags-author.html | 13 ++--- tags-borrows.html | 13 ++--- tags-callback.html | 21 +++---- tags-class.html | 11 ++-- tags-classdesc.html | 17 +++--- tags-constant.html | 18 +++--- tags-constructs.html | 12 ++-- tags-copyright.html | 8 +-- tags-default.html | 19 +++---- tags-deprecated.html | 13 ++--- tags-description.html | 24 ++++---- tags-enum.html | 15 ++--- tags-event.html | 24 ++++---- tags-example.html | 11 ++-- tags-exports.html | 32 +++++------ tags-external.html | 18 ++---- tags-file.html | 8 +-- tags-fires.html | 13 ++--- tags-function.html | 19 +++---- tags-generator.html | 9 +-- tags-global.html | 12 ++-- tags-hideconstructor.html | 12 ++-- tags-ignore.html | 9 +-- tags-implements.html | 9 +-- tags-inheritdoc.html | 9 +-- tags-inline-link.html | 12 ++-- tags-inline-tutorial.html | 9 +-- tags-inner.html | 16 +++--- tags-instance.html | 19 +++---- tags-interface.html | 15 ++--- tags-kind.html | 46 +++++++--------- tags-lends.html | 18 ++---- tags-license.html | 12 ++-- tags-listens.html | 9 +-- tags-member.html | 18 +++--- tags-memberof.html | 44 +++++++-------- tags-mixes.html | 20 +++---- tags-mixin.html | 13 ++--- tags-module.html | 35 +++++------- tags-name.html | 26 ++++----- tags-namespace.html | 28 ++++------ tags-override.html | 6 +- tags-package.html | 12 ++-- tags-param.html | 39 +++++-------- tags-private.html | 12 ++-- tags-property.html | 8 +-- tags-protected.html | 12 ++-- tags-public.html | 6 +- tags-readonly.html | 13 ++--- tags-requires.html | 14 ++--- tags-see.html | 16 ++---- tags-since.html | 11 ++-- tags-static.html | 15 ++--- tags-summary.html | 8 +-- tags-this.html | 11 ++-- tags-throws.html | 24 +++----- tags-todo.html | 12 ++-- tags-tutorial.html | 6 +- tags-type.html | 18 +++--- tags-typedef.html | 20 +++---- tags-variation.html | 24 ++++---- tags-version.html | 8 +-- tags-yields.html | 12 ++-- 85 files changed, 570 insertions(+), 929 deletions(-) diff --git a/about-block-inline-tags.html b/about-block-inline-tags.html index 0bcce6a1..29980f62 100644 --- a/about-block-inline-tags.html +++ b/about-block-inline-tags.html @@ -55,8 +55,7 @@

Examples

Shoe.prototype.setColor = function(color) { // ... }; - - +

You can use inline tags within a description, as shown above, or within a block tag, as shown below:

Inline tag used within a block tag
/**
@@ -68,8 +67,7 @@ 
Examples

 Shoe.prototype.setColor = function(color) {
     // ...
 };
-
-
+

When you use multiple block tags in a JSDoc comment, they must be separated by line breaks:

Multiple block tags separated by line breaks
/**
@@ -81,13 +79,11 @@ 
Examples

 Shoe.prototype.setLaceType = function(color, type) {
     // ...
 };
-
-
+