Block and inline tags
-Table of Contents
- -Overview
-JSDoc supports two different kinds of tags:
--
-
- Block tags, which are at the top level of a JSDoc comment. -
- Inline tags, which are within the text of a block tag or a description. -
Block tags usually provide detailed information about your code, such as the parameters that a
- function accepts. Inline tags usually link to other parts of the documentation, similar to the
- anchor tag (<a>) in HTML.
Block tags always begin with an at sign (@). Each block tag must be followed by a line break,
- with the exception of the last block tag in a JSDoc comment.
Inline tags also begin with an at sign. However, inline tags and their text must be enclosed in
- curly braces ({ and }). The { denotes the start of the inline tag, and the } denotes the end
- of the inline tag. If your tag's text includes a closing curly brace (}), you must escape it with
- a leading backslash (\). You do not need to use a line break after inline tags.
Most JSDoc tags are block tags. In general, when this site refers to "JSDoc tags," we really mean - "block tags."
-Examples
-In the following example, @param is a block tag, and {@link} is an inline tag:
/**
- * Set the shoe's color. Use {@link Shoe#setSize} to set the shoe size.
- *
- * @param {string} color - The shoe's color.
- */
-Shoe.prototype.setColor = function(color) {
- // ...
-};
-You can use inline tags within a description, as shown above, or within a block tag, as shown below:
-/**
- * Set the shoe's color.
- *
- * @param {SHOE_COLORS} color - The shoe color. Must be an enumerated
- * value of {@link SHOE_COLORS}.
- */
-Shoe.prototype.setColor = function(color) {
- // ...
-};
-When you use multiple block tags in a JSDoc comment, they must be separated by line breaks:
-/**
- * Set the color and type of the shoelaces.
- *
- * @param {LACE_COLORS} color - The shoelace color.
- * @param {LACE_TYPES} type - The type of shoelace.
- */
-Shoe.prototype.setLaceType = function(color, type) {
- // ...
-};
-
`.
-{% endexample %}
+
## Showing the current date in the page footer
diff --git a/content/en/about-configuring-jsdoc.md b/docs/about-configuring-jsdoc.md
similarity index 68%
rename from content/en/about-configuring-jsdoc.md
rename to docs/about-configuring-jsdoc.md
index b2e195c5..6a6428d9 100644
--- a/content/en/about-configuring-jsdoc.md
+++ b/docs/about-configuring-jsdoc.md
@@ -12,9 +12,9 @@ related:
To customize JSDoc's behavior, you can provide a configuration file to JSDoc in one of the following
formats:
-+ A JSON file. In JSDoc 3.3.0 and later, this file may include comments.
-+ A CommonJS module that exports a single configuration object. This format is supported in JSDoc
-3.5.0 and later.
+- A JSON file. In JSDoc 3.3.0 and later, this file may include comments.
+- A CommonJS module that exports a single configuration object. This format is supported in JSDoc
+ 3.5.0 and later.
To run JSDoc with a configuration file, use the [`-c` command-line option][about-commandline] (for
example, `jsdoc -c /path/to/conf.json` or `jsdoc -c /path/to/conf.js`).
@@ -22,7 +22,7 @@ example, `jsdoc -c /path/to/conf.json` or `jsdoc -c /path/to/conf.js`).
The following examples show a simple configuration file that enables JSDoc's [Markdown
plugin][markdown]. JSDoc's configuration options are explained in detail in the following sections.
-{% example "JSON configuration file" %}
+- **JSON configuration file**
```js
{
@@ -30,33 +30,29 @@ plugin][markdown]. JSDoc's configuration options are explained in detail in the
}
```
-{% endexample %}
-
-{% example "JavaScript configuration file" %}
+- **JavaScript configuration file**
```js
'use strict';
module.exports = {
- plugins: ['plugins/markdown']
+ plugins: ['plugins/markdown'],
};
```
-{% endexample %}
-
For a more comprehensive example of a JSON configuration file, see the file
[`conf.json.EXAMPLE`][conf-json-example].
-[about-commandline]: about-commandline.html
+[about-commandline]: about-commandline
[conf-json-example]: https://github.com/jsdoc3/jsdoc/blob/master/conf.json.EXAMPLE
-[markdown]: plugins-markdown.html
-
+[markdown]: plugins-markdown
## Default configuration options
If you do not specify a configuration file, JSDoc uses the following configuration options:
-{% example %}
+
+
```js
{
"plugins": [],
@@ -76,30 +72,28 @@ If you do not specify a configuration file, JSDoc uses the following configurati
}
}
```
-{% endexample %}
This means:
-+ No plugins are loaded (`plugins`).
-+ If recursion is enabled with the [`-r` command-line flag][about-commandline], JSDoc will search
-for files 10 levels deep (`recurseDepth`).
-+ Only files ending in `.js`, `.jsdoc`, and `.jsx` will be processed (`source.includePattern`).
-+ Any file starting with an underscore, or in a directory starting with an underscore, will be
-ignored (`source.excludePattern`).
-+ JSDoc supports code that uses [ES2015 modules][es2015-modules] (`sourceType`).
-+ JSDoc allows you to use unrecognized tags (`tags.allowUnknownTags`).
-+ Both standard JSDoc tags and [Closure Compiler tags][closure-tags] are enabled
-(`tags.dictionaries`).
-+ [Inline `{@link}` tags][tags-inline-link] are rendered in plain text (`templates.cleverLinks`,
-`templates.monospaceLinks`).
+- No plugins are loaded (`plugins`).
+- If recursion is enabled with the [`-r` command-line flag][about-commandline], JSDoc will search
+ for files 10 levels deep (`recurseDepth`).
+- Only files ending in `.js`, `.jsdoc`, and `.jsx` will be processed (`source.includePattern`).
+- Any file starting with an underscore, or in a directory starting with an underscore, will be
+ ignored (`source.excludePattern`).
+- JSDoc supports code that uses [ES2015 modules][es2015-modules] (`sourceType`).
+- JSDoc allows you to use unrecognized tags (`tags.allowUnknownTags`).
+- Both standard JSDoc tags and [Closure Compiler tags][closure-tags] are enabled
+ (`tags.dictionaries`).
+- [Inline `{@link}` tags][tags-inline-link] are rendered in plain text (`templates.cleverLinks`,
+ `templates.monospaceLinks`).
These options and others are explained in the following sections.
-[about-commandline]: about-commandline.html
+[about-commandline]: about-commandline
[closure-tags]: https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler#jsdoc-tags
-[es2015-modules]: howto-es2015-modules.html
-[tags-inline-link]: tags-inline-link.html
-
+[es2015-modules]: howto-es2015-modules
+[tags-inline-link]: tags-inline-link
## Configuring plugins
@@ -109,7 +103,7 @@ For example, the following JSON configuration file will enable the Markdown plug
Markdown-formatted text to HTML, and the "summarize" plugin, which autogenerates a summary for each
doclet:
-{% example "JSON configuration file with plugins" %}
+- **JSON configuration file with plugins**
```
{
@@ -119,7 +113,6 @@ doclet:
]
}
```
-{% endexample %}
See the [plugin reference][plugins] for further information, and look in [JSDoc's `plugins`
directory][jsdoc-plugins] for the plugins built into JSDoc.
@@ -128,9 +121,8 @@ You can configure the Markdown plugin by adding a `markdown` object to your conf
[Configuring the Markdown Plugin][markdown] for details.
[jsdoc-plugins]: https://github.com/jsdoc3/jsdoc/tree/master/plugins
-[markdown]: plugins-markdown.html
-[plugins]: about-plugins.html
-
+[markdown]: plugins-markdown
+[plugins]: about-plugins
## Specifying recursion depth
@@ -139,24 +131,22 @@ files and tutorials. This option is available in JSDoc 3.5.0 and later. This opt
you also specify the [`-r` command-line flag][about-commandline], which tells JSDoc to recursively
search for input files.
-{% example %}
+
```js
{
"recurseDepth": 10
}
```
-{% endexample %}
-
-[about-commandline]: about-commandline.html
+[about-commandline]: about-commandline
## Specifying input files
The `source` set of options, in combination with paths given to JSDoc on the command line,
determines the set of input files that JSDoc uses to generate documentation.
-{% example %}
+
```js
{
@@ -168,36 +158,35 @@ determines the set of input files that JSDoc uses to generate documentation.
}
}
```
-{% endexample %}
-
-+ `source.include`: An optional array of paths that contain files for which JSDoc should generate
-documentation. The paths given to JSDoc on the command line are combined with these paths. You can
-use the [`-r` command-line option][about-commandline] to recurse into subdirectories.
-+ `source.exclude`: An optional array of paths that JSDoc should ignore. In JSDoc 3.3.0 and later,
-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
-`.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
-beginning with an underscore (or anything under a directory beginning with an underscore) is
-ignored.
+
+- `source.include`: An optional array of paths that contain files for which JSDoc should generate
+ documentation. The paths given to JSDoc on the command line are combined with these paths. You can
+ use the [`-r` command-line option][about-commandline] to recurse into subdirectories.
+- `source.exclude`: An optional array of paths that JSDoc should ignore. In JSDoc 3.3.0 and later,
+ 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
+ `.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
+ beginning with an underscore (or anything under a directory beginning with an underscore) is
+ ignored.
These options are interpreted in the following order:
1. Start with all paths given on the command line and in `source.include`.
2. For each file found in Step 1, if the regular expression `source.includePattern` is present, the
-filename must match it, or it is ignored.
+ filename must match it, or it is ignored.
3. For each file left from Step 2, if the regular expression `source.excludePattern` is present, any
-filename matching this regular expression is ignored.
+ filename matching this regular expression is ignored.
4. For each file left from Step 3, if the file's path is in `source.exclude`, it is ignored.
All remaining files after these four steps are processed by JSDoc.
As an example, suppose you have the following file structure:
-{% example %}
+
```
myProject/
@@ -211,11 +200,10 @@ myProject/
|- ignore.js
|- d.txt
```
-{% endexample %}
In addition, suppose your `conf.json` file looks like this example:
-{% example %}
+
```js
{
@@ -227,50 +215,43 @@ In addition, suppose your `conf.json` file looks like this example:
}
}
```
-{% endexample %}
If you run `jsdoc myProject/c.js -c /path/to/my/conf.json -r` from the file containing the
`myProject` folder, JSDoc will generate documentation for the following files:
-+ `myProject/a.js`
-+ `myProject/c.js`
-+ `myProject/lib/a.js`
+- `myProject/a.js`
+- `myProject/c.js`
+- `myProject/lib/a.js`
Here's why:
-1. Given `source.include` and the paths given on the command line, JSDoc starts off with these
-files:
- + `myProject/c.js` (from the command line)
- + `myProject/a.js` (from `source.include`)
- + `myProject/lib/a.js`, `myProject/lib/ignore.js`, `myProject/lib/d.txt` (from `source.include`
- and using the `-r` option)
- + `myProject/_private/a.js` (from `source.include`)
-2. JSDoc applies `source.includePattern`, leaving us with all of the above files _except_
-`myProject/lib/d.txt`, which does not end in `.js`, `.jsdoc`, or `.jsx`.
+1. Given `source.include` and the paths given on the command line, JSDoc starts off with these files:
+ - `myProject/c.js` (from the command line)
+ - `myProject/a.js` (from `source.include`)
+ - `myProject/lib/a.js`, `myProject/lib/ignore.js`, `myProject/lib/d.txt` (from `source.include` and using the `-r` option)
+ - `myProject/_private/a.js` (from `source.include`)
+2. JSDoc applies `source.includePattern`, leaving us with all of the above files _except_ `myProject/lib/d.txt`, which does not end in `.js`, `.jsdoc`, or `.jsx`.
3. JSDoc applies `source.excludePattern`, which removes `myProject/_private/a.js`.
4. JSDoc applies `source.exclude`, which removes `myProject/lib/ignore.js`.
-[about-commandline]: about-commandline.html
-
+[about-commandline]: about-commandline
## Specifying the source type
The `sourceType` option affects how JSDoc parses your JavaScript files. This option is available in
JSDoc 3.5.0 and later. This option accepts the following values:
-+ `module` (default): Use this value for most types of JavaScript files.
-+ `script`: Use this value if JSDoc logs errors such as `Delete of an unqualified identifier in
+- `module` (default): Use this value for most types of JavaScript files.
+- `script`: Use this value if JSDoc logs errors such as `Delete of an unqualified identifier in
strict mode` when it parses your code.
-{% example %}
+
```js
{
"sourceType": "module"
}
```
-{% endexample %}
-
## Incorporating command-line options into the configuration file
@@ -278,9 +259,9 @@ You can put many of JSDoc's [command-line options][options] into the configurati
specifying them on the command line. To do this, add the long names of the relevant options into an
`opts` section of the configuration file, with the value set to the option's value.
-[options]: about-commandline.html
+[options]: about-commandline
-{% example "JSON configuration file with command-line options" %}
+- **JSON configuration file with command-line options**
```js
{
@@ -293,7 +274,6 @@ specifying them on the command line. To do this, add the long names of the relev
}
}
```
-{% endexample %}
By using the `source.include` and `opts` options, you can put almost all of the arguments to JSDoc
in a configuration file, so that the command line reduces to:
@@ -305,12 +285,11 @@ jsdoc -c /path/to/conf.json
When options are specified on the command line _and_ in the configuration file, the command line
takes precedence.
-
## Configuring tags and tag dictionaries
The options in `tags` control which JSDoc tags are allowed and how each tag is interpreted.
-{% example %}
+
```js
{
@@ -320,7 +299,6 @@ The options in `tags` control which JSDoc tags are allowed and how each tag is i
}
}
```
-{% endexample %}
The `tags.allowUnknownTags` property affects how JSDoc handles unrecognized tags. If you set this
option to `false`, and JSDoc finds a tag that it does not recognize (for example, `@foo`), JSDoc
@@ -331,8 +309,8 @@ The `tags.dictionaries` property controls which tags JSDoc recognizes, as well a
interprets the tags that it recognizes. In JSDoc 3.3.0 and later, there are two built-in tag
dictionaries:
-+ `jsdoc`: Core JSDoc tags.
-+ `closure`: [Closure Compiler tags][closure-tags].
+- `jsdoc`: Core JSDoc tags.
+- `closure`: [Closure Compiler tags][closure-tags].
By default, both dictionaries are enabled. Also, by default, the `jsdoc` dictionary is listed first;
as a result, if the `jsdoc` dictionary handles a tag differently than the `closure` dictionary, the
@@ -346,14 +324,13 @@ interpret them.
[closure-tags]: https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler#jsdoc-tags
-
## Configuring templates
The options in `templates` affect the appearance and content of generated documentation. Third-party
templates may not implement all of these options. See [Configuring JSDoc's Default
Template][default-template] for additional options that the default template supports.
-{% example %}
+
```js
{
@@ -363,7 +340,6 @@ Template][default-template] for additional options that the default template sup
}
}
```
-{% endexample %}
If `templates.monospaceLinks` is true, all link text from the [inline `{@link}`
tag][inline-link-tag] will be rendered in monospace.
@@ -374,5 +350,5 @@ but `{@link MyNamespace.myFunction}` will be in monospace.
If `templates.cleverLinks` is true, `templates.monospaceLinks` is ignored.
-[default-template]: about-configuring-default-template.html
-[inline-link-tag]: tags-inline-link.html
+[default-template]: about-configuring-default-template
+[inline-link-tag]: tags-inline-link
diff --git a/content/en/about-getting-started.md b/docs/about-getting-started.md
similarity index 85%
rename from content/en/about-getting-started.md
rename to docs/about-getting-started.md
index f534fc6a..8d848af6 100644
--- a/content/en/about-getting-started.md
+++ b/docs/about-getting-started.md
@@ -20,36 +20,32 @@ must start with a `/**` sequence in order to be recognized by the JSDoc parser.
with `/*`, `/***`, or more than 3 stars will be ignored. This is a feature to allow you to suppress
parsing of comment blocks.
-{% example "The simplest documentation is just a description" %}
+- **The simplest documentation is just a description**
```js
/** This is a description of the foo function. */
-function foo() {
-}
+function foo() {}
```
-{% endexample %}
Adding a description is simple—just type the description you want in the documentation comment.
Special "JSDoc tags" can be used to give more information. For example, if the function is a
constructor for a class, you can indicate this by adding a `@constructor` tag.
-{% example "Use a JSDoc tag to describe your code" %}
+- **Use a JSDoc tag to describe your code**
```js
/**
* Represents a book.
* @constructor
*/
-function Book(title, author) {
-}
+function Book(title, author) {}
```
-{% endexample %}
More tags can be used to add more information. See the [home page][block-tags] for a complete list
of tags that are recognized by JSDoc 3.
-{% example "Adding more information with tags" %}
+- **Adding more information with tags**
```js
/**
@@ -58,10 +54,8 @@ of tags that are recognized by JSDoc 3.
* @param {string} title - The title of the book.
* @param {string} author - The author of the book.
*/
-function Book(title, author) {
-}
+function Book(title, author) {}
```
-{% endexample %}
[block-tags]: index.html#block-tags
@@ -74,12 +68,11 @@ By default, JSDoc uses the built-in "default" template to turn the documentation
edit this template to suit your own needs or create an entirely new template if that is what you
prefer.
-{% example "Running the documentation generator on the command line" %}
+- **Running the documentation generator on the command line**
```
jsdoc book.js
```
-{% endexample %}
This command will create a directory named `out/` in the current working directory. Within that
directory, you will find the generated HTML pages.
diff --git a/content/en/about-including-package.md b/docs/about-including-package.md
similarity index 90%
rename from content/en/about-including-package.md
rename to docs/about-including-package.md
index 8d2dff1f..280c8ab5 100644
--- a/content/en/about-including-package.md
+++ b/docs/about-including-package.md
@@ -25,16 +25,16 @@ The `package.json` file must use [npm's package format][package-json].
## Examples
-{% example "Including a package file in your source paths" %}
+- **Including a package file in your source paths**
```
jsdoc path/to/js path/to/package/package.json
```
-{% endexample %}
-{% example "Using the -P/--package option" %}
+
+- **Using the -P/--package option**
```
jsdoc --package path/to/package/package-docs.json path/to/js
```
-{% endexample %}
+
diff --git a/content/en/about-including-readme.md b/docs/about-including-readme.md
similarity index 69%
rename from content/en/about-including-readme.md
rename to docs/about-including-readme.md
index 510bfb99..a779ccaf 100644
--- a/content/en/about-including-readme.md
+++ b/docs/about-including-readme.md
@@ -6,10 +6,10 @@ description: How to include a README file in your documentation.
There are two ways to incorporate a `README` file into your documentation:
1. In the source paths to your JavaScript files, include the path to a Markdown file named
-`README.md`. JSDoc will use the first `README.md` file that it finds in your source paths.
+ `README.md`. JSDoc will use the first `README.md` file that it finds in your source paths.
2. Run JSDoc with the `-R/--readme` command-line option, specifying the path to your `README` file.
-This option is available in JSDoc 3.3.0 and later. The `README` file may have any name and
-extension, but it must be in Markdown format.
+ This option is available in JSDoc 3.3.0 and later. The `README` file may have any name and
+ extension, but it must be in Markdown format.
The `-R/--readme` command-line option takes precedence over your source paths. If you use the
`-R/--readme` command-line option, JSDoc will ignore any `README.md` files in your source paths.
@@ -17,19 +17,20 @@ The `-R/--readme` command-line option takes precedence over your source paths. I
If you are using JSDoc's default template, the `README` file's contents will be rendered in HTML
in the generated documentation's `index.html` file.
-
## Examples
-{% example "Including a README file in your source paths" %}
+- **Including a README file in your source paths**
```
jsdoc path/to/js path/to/readme/README.md
```
-{% endexample %}
-{% example "Using the -R/--readme option" %}
+
+
+- **Using the -R/--readme option**
```
jsdoc --readme path/to/readme/README path/to/js
```
-{% endexample %}
+
+
diff --git a/content/en/about-license-jsdoc3.md b/docs/about-license-jsdoc3.md
similarity index 100%
rename from content/en/about-license-jsdoc3.md
rename to docs/about-license-jsdoc3.md
diff --git a/content/en/about-namepaths.md b/docs/about-namepaths.md
similarity index 79%
rename from content/en/about-namepaths.md
rename to docs/about-namepaths.md
index d42b6ade..478d516e 100644
--- a/content/en/about-namepaths.md
+++ b/docs/about-namepaths.md
@@ -10,7 +10,7 @@ related:
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.
-{% example "Basic Syntax Examples of Namepaths in JSDoc 3" %}
+- **Basic Syntax Examples of Namepaths in JSDoc 3**
```
myFunction
@@ -19,75 +19,70 @@ MyConstructor#instanceMember
MyConstructor.staticMember
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.
-{% example "Use a documentation tag to describe your code." %}
+- **Use a documentation tag to describe your code.**
```js
/** @constructor */
-Person = function() {
- this.say = function() {
+Person = function () {
+ this.say = function () {
return "I'm an instance.";
- }
+ };
function say() {
return "I'm inner.";
}
-}
-Person.say = function() {
+};
+Person.say = function () {
return "I'm static.";
-}
+};
var p = new Person();
-p.say(); // I'm an instance.
+p.say(); // I'm an instance.
Person.say(); // I'm static.
// there is no way to directly access the inner function from here
```
-{% endexample %}
You would use three different namepath syntaxes to refer to the three different methods:
-{% example "Use a documentation tag to describe your code." %}
+- **Use a documentation tag to describe your code.**
```
Person#say // the instance method named "say."
Person.say // the static method named "say."
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.
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:
-{% example "Use a documentation tag to describe your code." %}
+- **Use a documentation tag to describe your code.**
```js
/** @constructor */
-Person = function() {
+Person = function () {
/** @constructor */
- this.Idea = function() {
- this.consider = function(){
- return "hmmm";
- }
- }
-}
+ this.Idea = function () {
+ this.consider = function () {
+ return 'hmmm';
+ };
+ };
+};
var p = new Person();
var i = new p.Idea();
i.consider();
```
-{% endexample %}
In this case, to refer to the method named "consider," you would use the following namepath:
`Person#Idea#consider`
-
This chaining can be used with any combination of the connecting symbols: `# . ~`
-{% example "Special cases: modules, externals and events." %}
+- **Special cases: modules, externals and events.**
```js
/** A module. Its name is module:foo/bar.
@@ -100,11 +95,10 @@ This chaining can be used with any combination of the connecting symbols: `# . ~
* @event module:foo/bar.event:MyEvent
*/
```
-{% 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:".
-{% example "Namepaths of objects with special characters in the name." %}
+- **Namepaths of objects with special characters in the name.**
```js
/** @namespace */
@@ -113,7 +107,7 @@ var chat = {
* Refer to this by {@link chat."#channel"}.
* @namespace
*/
- "#channel": {
+ '#channel': {
/**
* Refer to this by {@link chat."#channel".open}.
* @type {boolean}
@@ -124,8 +118,8 @@ var chat = {
* Internal quotes have to be escaped by backslash. This is
* {@link chat."#channel"."say-\"hello\""}.
*/
- 'say-"hello"': function (msg) {}
- }
+ 'say-"hello"': function (msg) {},
+ },
};
/**
@@ -133,12 +127,11 @@ var chat = {
* @event chat."#channel"."op:announce-motd"
*/
```
-{% 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\"".
-[event-tag]: tags-event.html
-[external-tag]: tags-external.html
-[module-tag]: tags-module.html
+[event-tag]: tags-event
+[external-tag]: tags-external
+[module-tag]: tags-module
diff --git a/content/en/about-plugins.md b/docs/about-plugins.md
similarity index 96%
rename from content/en/about-plugins.md
rename to docs/about-plugins.md
index 20723f7c..05fdb3c3 100644
--- a/content/en/about-plugins.md
+++ b/docs/about-plugins.md
@@ -17,18 +17,18 @@ For example, if your plugin is defined in the `plugins/shout.js` file in the cur
directory, you would add the string `plugins/shout` to the `plugins` array in your JSDoc
configuration file:
-{% example "Adding a plugin to JSDoc's configuration file" %}
+- **Adding a plugin to JSDoc's configuration file**
```json
{
"plugins": ["plugins/shout"]
}
```
-{% endexample %}
+
JSDoc executes plugins in the order that they are listed in the configuration file.
-[config-file]: about-configuring-jsdoc.html
+[config-file]: about-configuring-jsdoc
## Authoring JSDoc 3 Plugins
@@ -46,7 +46,7 @@ At the highest level, a plugin may register handlers for specific named events t
JSDoc will pass an event object to the handler. Your plugin module should export a `handlers` object
that contains your handler, like so:
-{% example "Event-handler plugin for 'newDoclet' events" %}
+- **Event-handler plugin for 'newDoclet' events**
```js
exports.handlers = {
@@ -55,7 +55,7 @@ exports.handlers = {
}
};
```
-{% endexample %}
+
JSDoc fires events in the same order as the underlying code.
@@ -99,7 +99,7 @@ parsed and added to the documentation. This might be done to document methods th
to users, but might not appear in the source code being documented, such as methods provided by an
external superclass:
-{% example "Example" %}
+- **Example**
```js
exports.handlers = {
@@ -116,7 +116,7 @@ exports.handlers = {
}
};
```
-{% endexample %}
+
#### Event: jsdocCommentFound
@@ -189,7 +189,7 @@ option][about-commandline].
Below is an example of a `newDoclet` handler that shouts the descriptions:
-{% example "Example" %}
+- **Example**
```js
exports.handlers = {
@@ -202,9 +202,9 @@ exports.handlers = {
}
};
```
-{% endexample %}
-[about-commandline]: about-commandline.html
+
+[about-commandline]: about-commandline
#### Event: fileComplete
@@ -254,14 +254,14 @@ it is given a chance to modify the doclet.
Plugins can define tags by exporting a `defineTags` function. That function will be passed a
dictionary that can be used to define tags, like so:
-{% example "Example" %}
+- **Example**
```js
exports.defineTags = function(dictionary) {
// define tags here
};
```
-{% endexample %}
+
#### The Dictionary
@@ -295,7 +295,7 @@ synonym for `@constant`; as a result, if you call `normalise('const')`, it retur
A tag's `onTagged` callback can modify the contents of the doclet or tag.
-{% example "Defining an onTagged callback" %}
+- **Defining an onTagged callback**
```js
dictionary.defineTag('instance', {
@@ -304,18 +304,18 @@ dictionary.defineTag('instance', {
}
});
```
-{% endexample %}
+
The `defineTag` method returns a `Tag` object, which has a `synonym` method that can be used to
declare a synonym for the tag.
-{% example "Defining a tag synonym" %}
+- **Defining a tag synonym**
```js
dictionary.defineTag('exception', { /* options for exception tag */ })
.synonym('throws');
```
-{% endexample %}
+
### Node Visitors
@@ -326,7 +326,7 @@ comments and trigger parser events for any arbitrary piece of code.
Plugins can define a node visitor by exporting an `astNodeVisitor` object that contains a
`visitNode` function, like so:
-{% example "Example" %}
+- **Example**
```js
exports.astNodeVisitor = {
@@ -335,7 +335,7 @@ exports.astNodeVisitor = {
}
};
```
-{% endexample %}
+
The function is called on each node with the following parameters:
@@ -386,7 +386,7 @@ Using these methods creates a better user experience than simply throwing an err
**Note**: Do not use the `jsdoc/util/error` module to report errors. This module is deprecated and
will be removed in a future version of JSDoc.
-{% example "Reporting a non-fatal error" %}
+- **Reporting a non-fatal error**
```js
var logger = require('jsdoc/util/logger');
@@ -401,4 +401,4 @@ exports.handlers = {
}
};
```
-{% endexample %}
+
diff --git a/content/en/about-tutorials.md b/docs/about-tutorials.md
similarity index 93%
rename from content/en/about-tutorials.md
rename to docs/about-tutorials.md
index a3743391..54d3aec7 100644
--- a/content/en/about-tutorials.md
+++ b/docs/about-tutorials.md
@@ -34,8 +34,8 @@ In tutorial files, you can use the [`{@link}`][link-inline-tag] and
[`{@tutorial}`][tutorial-inline-tag] inline tags to link to other parts of the documentation. JSDoc
will automatically resolve the links.
-[link-inline-tag]: tags-inline-link.html
-[tutorial-inline-tag]: tags-inline-tutorial.html
+[link-inline-tag]: tags-inline-link
+[tutorial-inline-tag]: tags-inline-tutorial
## Configuring titles, order, and hierarchy
@@ -110,7 +110,7 @@ There are multiple ways to link to a tutorial from your API documentation:
If you include a [`@tutorial` block tag][tutorial-block-tag] in a JSDoc comment, the generated documentation
will include a link to the tutorial you specify.
-{% example "Using the `@tutorial` block tag" %}
+- **Using the `@tutorial` block tag**
```js
@@ -122,14 +122,14 @@ will include a link to the tutorial you specify.
*/
function Socket() {}
```
-{% endexample %}
+
### {@tutorial} inline tag
You can also use the [`{@tutorial}` inline tag][tutorial-inline-tag] to link to a tutorial within the text
of another tag. By default, JSDoc will use the tutorial's title as the link text.
-{% example "Using the `{@tutorial}` inline tag" %}
+- **Using the `{@tutorial}` inline tag**
```js
/**
@@ -140,7 +140,7 @@ of another tag. By default, JSDoc will use the tutorial's title as the link text
*/
function Socket() {}
```
-{% endexample %}
-[tutorial-block-tag]: tags-tutorial.html
-[tutorial-inline-tag]: tags-inline-tutorial.html
+
+[tutorial-block-tag]: tags-tutorial
+[tutorial-inline-tag]: tags-inline-tutorial
diff --git a/docs/contribute.md b/docs/contribute.md
new file mode 100644
index 00000000..07b8bf17
--- /dev/null
+++ b/docs/contribute.md
@@ -0,0 +1,8 @@
+# Contribute
+
+We welcome you to contribute to JSDoc on GitHub.
+
+## GitHub Links
+
+- [JSDoc](https://github.com/jsdoc/jsdoc)
+- [JSDoc documentation](https://github.com/jsdoc/jsdoc.github.io)
diff --git a/content/en/howto-amd-modules.md b/docs/howto-amd-modules.md
similarity index 88%
rename from content/en/howto-amd-modules.md
rename to docs/howto-amd-modules.md
index 0d2d2fbf..15f50c16 100644
--- a/content/en/howto-amd-modules.md
+++ b/docs/howto-amd-modules.md
@@ -16,9 +16,9 @@ how to document an AMD module for JSDoc, based on the coding conventions that yo
If you're documenting CommonJS or Node.js modules, see [CommonJS Modules][commonjs-modules] for
instructions.
-[amd-modules]: howto-amd-modules.html
+[amd-modules]: howto-amd-modules
[amd-api]: https://github.com/amdjs/amdjs-api/blob/master/AMD.md
-[commonjs-modules]: howto-commonjs-modules.html
+[commonjs-modules]: howto-commonjs-modules
[require-js]: http://requirejs.org/
@@ -50,10 +50,10 @@ Similarly, the namepath for each member of the module will start with `module:`,
module name. For example, if your `my/pants` module exports a `Jeans` constructor, and `Jeans` has
an instance method named `hem`, the instance method's longname is `module:my/pants.Jeans#hem`.
-[exports-tag]: tags-exports.html
-[module-tag]: tags-module.html
-[namepaths]: about-namepaths.html
-[see-tag]: tags-see.html
+[exports-tag]: tags-exports
+[module-tag]: tags-module
+[namepaths]: about-namepaths
+[see-tag]: tags-see
## Function that returns an object literal
@@ -62,7 +62,7 @@ If you define your AMD module as a function that returns an object literal, use
[`@exports` tag][exports-tag] to document the module's name. JSDoc will automatically detect that
the object's properties are members of the module.
-{% example "Function that returns an object literal" %}
+- **Function that returns an object literal**
```js
define('my/shirt', function() {
@@ -88,9 +88,9 @@ define('my/shirt', function() {
return shirt;
});
```
-{% endexample %}
-[exports-tag]: tags-exports.html
+
+[exports-tag]: tags-exports
## Function that returns another function
@@ -100,7 +100,7 @@ can use a standalone comment with a [`@module` tag][module-tag] to document the
use an [`@alias` tag][alias-tag] to tell JSDoc that the function uses the same longname as the
module.
-{% example "Function that returns a constructor" %}
+- **Function that returns a constructor**
```js
/**
@@ -125,10 +125,10 @@ define('my/jacket', function() {
return Jacket;
});
```
-{% endexample %}
-[alias-tag]: tags-alias.html
-[module-tag]: tags-module.html
+
+[alias-tag]: tags-alias
+[module-tag]: tags-module
## Module declared in a return statement
@@ -137,7 +137,7 @@ If you declare your module object in a function's `return` statement, you can us
comment with a [`@module` tag][module-tag] to document the module. You can then add an
[`@alias` tag][alias-tag] to tell JSDoc that the module object has the same longname as the module.
-{% example "Module declared in a return statement" %}
+- **Module declared in a return statement**
```js
/**
@@ -156,10 +156,10 @@ define('my/shirt', function() {
};
});
```
-{% endexample %}
-[alias-tag]: tags-alias.html
-[module-tag]: tags-module.html
+
+[alias-tag]: tags-alias
+[module-tag]: tags-module
## Module object passed to a function
@@ -168,7 +168,7 @@ If the module object is passed into the function that defines your module, you c
module by adding an [`@exports` tag][exports-tag] to the function parameter. This pattern is
supported in JSDoc 3.3.0 and later.
-{% example "Module object passed to a function" %}
+- **Module object passed to a function**
```js
define('my/jacket', function(
@@ -187,9 +187,9 @@ define('my/jacket', function(
};
});
```
-{% endexample %}
-[exports-tag]: tags-exports.html
+
+[exports-tag]: tags-exports
## Multiple modules defined in one file
@@ -197,7 +197,7 @@ define('my/jacket', function(
If you define more than one AMD module in a single JavaScript file, use the
[`@exports` tag][exports-tag] to document each module object.
-{% example "Multiple AMD modules defined in one file" %}
+- **Multiple AMD modules defined in one file**
```js
// one module
@@ -245,6 +245,6 @@ define('tag', function() {
return tag;
});
```
-{% endexample %}
-[exports-tag]: tags-exports.html
+
+[exports-tag]: tags-exports
diff --git a/content/en/howto-commonjs-modules.md b/docs/howto-commonjs-modules.md
similarity index 88%
rename from content/en/howto-commonjs-modules.md
rename to docs/howto-commonjs-modules.md
index f9d6a857..140278f2 100644
--- a/content/en/howto-commonjs-modules.md
+++ b/docs/howto-commonjs-modules.md
@@ -22,7 +22,7 @@ known as "RequireJS modules"), see [AMD Modules][amd-modules].
[commonjs-modules]: http://wiki.commonjs.org/wiki/Modules/1.1
[node-modules]: http://nodejs.org/api/modules.html
-[amd-modules]: howto-amd-modules.html
+[amd-modules]: howto-amd-modules
## Module identifiers
@@ -52,9 +52,9 @@ Similarly, the namepath for each member of the module will start with `module:`,
module name. For example, if your `my/pants` module exports a `Jeans` constructor, and `Jeans` has
an instance method named `hem`, the instance method's longname is `module:my/pants.Jeans#hem`.
-[module-tag]: tags-module.html
-[namepaths]: about-namepaths.html
-[see-tag]: tags-see.html
+[module-tag]: tags-module
+[namepaths]: about-namepaths
+[see-tag]: tags-see
## Properties of the 'exports' object
@@ -65,7 +65,7 @@ JSDoc will automatically recognize that the module exports these symbols.
In the following example, the `my/shirt` module exports the methods `button` and `unbutton`. JSDoc
will automatically detect that the module exports these methods.
-{% example "Methods added to the exports object" %}
+- **Methods added to the exports object**
```js
/**
@@ -83,7 +83,7 @@ exports.unbutton = function() {
// ...
};
```
-{% endexample %}
+