Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update formatting for readability, aesthetics #187

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

Update formatting for readability, aesthetics #187

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
babfab0
docs: Format tags & variables instead of quoting
Zearin May 24, 2018
8aa5358
docs: Rebuild HTML
Zearin May 24, 2018
669c480
style(css): Slightly lighten background-color of code
Zearin May 24, 2018
934acd3
style(css): Prevent super-long text lines on big screens
Zearin May 24, 2018
7acaec4
style(css): Rounder is friendlier ☻
Zearin May 24, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 4 additions & 8 deletions about-block-inline-tags.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,8 +55,7 @@ <h2 id="examples">Examples</h2>
Shoe.prototype.setColor = function(color) {
// ...
};
</code></pre>
</figure>
</code></pre></figure>
<p>You can use inline tags within a description, as shown above, or within a block tag, as shown below:</p>
<figure>
<figcaption>Inline tag used within a block tag</figcaption><pre class="prettyprint lang-js"><code>/**
Expand All @@ -68,8 +67,7 @@ <h2 id="examples">Examples</h2>
Shoe.prototype.setColor = function(color) {
// ...
};
</code></pre>
</figure>
</code></pre></figure>
<p>When you use multiple block tags in a JSDoc comment, they must be separated by line breaks:</p>
<figure>
<figcaption>Multiple block tags separated by line breaks</figcaption><pre class="prettyprint lang-js"><code>/**
Expand All @@ -81,13 +79,11 @@ <h2 id="examples">Examples</h2>
Shoe.prototype.setLaceType = function(color, type) {
// ...
};
</code></pre>
</figure>
</code></pre></figure>
</article>
<footer>
<a class="license-badge" href="http://creativecommons.org/licenses/by-sa/3.0/">
<img alt="Creative Commons License" class="license-badge" src="images/cc-by-sa.svg" width="80" height="15" />
</a>
<img alt="Creative Commons License" class="license-badge" src="images/cc-by-sa.svg" width="80" height="15" /></a>
<br> Copyright &#169; 2011-2017 the
<a href="https://github.com/jsdoc3/jsdoc3.github.com/contributors">contributors</a> to the JSDoc 3 documentation project.
<br> This website is <a href="https://github.com/jsdoc3/jsdoc3.github.com">open source</a> and is licensed under the <a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/">
Expand Down
73 changes: 25 additions & 48 deletions about-commandline.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,8 +35,8 @@ <h2>Table of Contents</h2>
<pre class="prettyprint"><code>/path/to/jsdoc yourSourceCodeFile.js anotherSourceCodeFile.js ...
</code></pre>
<p>where <code>...</code> are paths to other files to generate documentation for.</p>
<p>Additionally, one may provide the path to a <a href="http://daringfireball.net/projects/markdown/">Markdown file</a> (ending in &quot;.md&quot;) or a file named
&quot;README&quot;, and this will be added to the documentation on the front page. See <a href="about-including-readme.html">these
<p>Additionally, one may provide the path to a <a href="http://daringfireball.net/projects/markdown/">Markdown file</a> (ending in <code>.md</code>) or a file named
<code>README</code>, and this will be added to the documentation on the front page. See <a href="about-including-readme.html">these
instructions</a>.</p>
<p>JSDoc supports a number of command-line options, many of which have both long and short forms. Alternatively, the command-line options may be <a href="about-configuring-jsdoc.html">specified in a configuration file</a> given to JSDoc. The command-line options are:</p>
<table>
Expand All @@ -48,107 +48,87 @@ <h2>Table of Contents</h2>
</thead>
<tbody>
<tr>
<td><code>-a &lt;value&gt;</code>, <code>--access &lt;value&gt;</code>
</td>
<td><code>-a &lt;value&gt;</code>, <code>--access &lt;value&gt;</code></td>
<td>Only display symbols with the given <code>access</code> property: <code>private</code>, <code>protected</code>, <code>public</code>, or <code>undefined</code>,
or <code>all</code> for all access levels. By default, all except <code>private</code> symbols are shown.</td>
</tr>
<tr>
<td><code>-c &lt;value&gt;</code>, <code>--configure &lt;value&gt;</code>
</td>
<td><code>-c &lt;value&gt;</code>, <code>--configure &lt;value&gt;</code></td>
<td>The path to a JSDoc <a href="about-configuring-jsdoc.html">configuration file</a>. Defaults to <code>conf.json</code> or <code>conf.json.EXAMPLE</code> in the directory where JSDoc is installed.</td>
</tr>
<tr>
<td><code>-d &lt;value&gt;</code>, <code>--destination &lt;value&gt;</code>
</td>
<td><code>-d &lt;value&gt;</code>, <code>--destination &lt;value&gt;</code></td>
<td>The path to the output folder for the generated documentation. For JSDoc&#39;s built-in Haruki template, use <code>console</code> to dump data to the console.
Defaults to <code>./out</code>.</td>
</tr>
<tr>
<td><code>--debug</code>
</td>
<td><code>--debug</code></td>
<td>Log information that can help debug issues in JSDoc itself.</td>
</tr>
<tr>
<td><code>-e &lt;value&gt;</code>, <code>--encoding &lt;value&gt;</code>
</td>
<td><code>-e &lt;value&gt;</code>, <code>--encoding &lt;value&gt;</code></td>
<td>Assume this encoding when reading all source files. Defaults to <code>utf8</code>.</td>
</tr>
<tr>
<td><code>-h</code>, <code>--help</code>
</td>
<td><code>-h</code>, <code>--help</code></td>
<td>Display information about JSDoc&#39;s command-line options, then exit.</td>
</tr>
<tr>
<td><code>--match &lt;value&gt;</code>
</td>
<td><code>--match &lt;value&gt;</code></td>
<td>Only run tests whose names contain <code>value</code>.</td>
</tr>
<tr>
<td><code>--nocolor</code>
</td>
<td><code>--nocolor</code></td>
<td>When running tests, do not use color in the console output. On Windows, this option is enabled by default.</td>
</tr>
<tr>
<td><code>-p</code>, <code>--private</code>
</td>
<td><code>-p</code>, <code>--private</code></td>
<td>Include symbols marked with the <a href="tags-private.html"><code>@private</code> tag</a> in the generated documentation. By default, private symbols are
not included.</td>
</tr>
<tr>
<td><code>-P</code>, <code>--package</code>
</td>
<td><code>-P</code>, <code>--package</code></td>
<td>The <code>package.json</code> file that contains the project name, version, and other details. Defaults to the first <code>package.json</code> file found
in the source paths.</td>
</tr>
<tr>
<td><code>--pedantic</code>
</td>
<td><code>--pedantic</code></td>
<td>Treat errors as fatal errors, and treat warnings as errors. Defaults to <code>false</code>.</td>
</tr>
<tr>
<td><code>-q &lt;value&gt;</code>, <code>--query &lt;value&gt;</code>
</td>
<td><code>-q &lt;value&gt;</code>, <code>--query &lt;value&gt;</code></td>
<td>A query string to parse and store in the global variable <code>env.opts.query</code>. Example: <code>foo=bar&amp;baz=true</code>.</td>
</tr>
<tr>
<td><code>-r</code>, <code>--recurse</code>
</td>
<td><code>-r</code>, <code>--recurse</code></td>
<td>Recurse into subdirectories when scanning for source files and tutorials.</td>
</tr>
<tr>
<td><code>-R</code>, <code>--readme</code>
</td>
<td><code>-R</code>, <code>--readme</code></td>
<td>The <code>README.md</code> file to include in the generated documentation. Defaults to the first <code>README.md</code> file found in the source paths.</td>
</tr>
<tr>
<td><code>-t &lt;value&gt;</code>, <code>--template &lt;value&gt;</code>
</td>
<td><code>-t &lt;value&gt;</code>, <code>--template &lt;value&gt;</code></td>
<td>The path to the template to use for generating output. Defaults to <code>templates/default</code>, JSDoc&#39;s built-in default template.</td>
</tr>
<tr>
<td><code>-T</code>, <code>--test</code>
</td>
<td><code>-T</code>, <code>--test</code></td>
<td>Run JSDoc&#39;s test suite, and print the results to the console.</td>
</tr>
<tr>
<td><code>-u &lt;value&gt;</code>, <code>--tutorials &lt;value&gt;</code>
</td>
<td><code>-u &lt;value&gt;</code>, <code>--tutorials &lt;value&gt;</code></td>
<td>Directory in which JSDoc should search for tutorials. If omitted, no tutorial pages will be generated. See the <a href="about-tutorials.html">tutorial instructions</a> for more information.</td>
</tr>
<tr>
<td><code>-v</code>, <code>--version</code>
</td>
<td><code>-v</code>, <code>--version</code></td>
<td>Displays JSDoc&#39;s version number, then exits.</td>
</tr>
<tr>
<td><code>--verbose</code>
</td>
<td><code>--verbose</code></td>
<td>Log detailed information to the console as JSDoc runs. Defaults to <code>false</code>.</td>
</tr>
<tr>
<td><code>-X</code>, <code>--explain</code>
</td>
<td><code>-X</code>, <code>--explain</code></td>
<td>Dump all doclets to the console in JSON format, then exit.</td>
</tr>
</tbody>
Expand All @@ -157,21 +137,18 @@ <h2 id="examples">Examples</h2>
<p>Generate documentation for files in the <code>./src</code> directory, using the configuration file
<code>/path/to/my/conf.json</code>, and save the output in the <code>./docs</code> directory:</p>
<figure><pre class="prettyprint"><code>/path/to/jsdoc src -r -c /path/to/my/conf.json -d docs
</code></pre>
</figure>
</code></pre></figure>
<p>Run all JSDoc tests whose names include the word <code>tag</code>, and log information about each test:</p>
<figure><pre class="prettyprint"><code>/path/to/jsdoc -T --match tag --verbose
</code></pre>
</figure>
</code></pre></figure>
<h2 id="related-links">Related Links</h2>
<p>
<a href="about-configuring-jsdoc.html">Configuring JSDoc with a configuration file</a>
</p>
</article>
<footer>
<a class="license-badge" href="http://creativecommons.org/licenses/by-sa/3.0/">
<img alt="Creative Commons License" class="license-badge" src="images/cc-by-sa.svg" width="80" height="15" />
</a>
<img alt="Creative Commons License" class="license-badge" src="images/cc-by-sa.svg" width="80" height="15" /></a>
<br> Copyright &#169; 2011-2017 the
<a href="https://github.com/jsdoc3/jsdoc3.github.com/contributors">contributors</a> to the JSDoc 3 documentation project.
<br> This website is <a href="https://github.com/jsdoc3/jsdoc3.github.com">open source</a> and is licensed under the <a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/">
Expand Down
3 changes: 1 addition & 2 deletions about-configuring-default-template.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,8 +103,7 @@ <h2 id="related-links">Related Links</h2>
</article>
<footer>
<a class="license-badge" href="http://creativecommons.org/licenses/by-sa/3.0/">
<img alt="Creative Commons License" class="license-badge" src="images/cc-by-sa.svg" width="80" height="15" />
</a>
<img alt="Creative Commons License" class="license-badge" src="images/cc-by-sa.svg" width="80" height="15" /></a>
<br> Copyright &#169; 2011-2017 the
<a href="https://github.com/jsdoc3/jsdoc3.github.com/contributors">contributors</a> to the JSDoc 3 documentation project.
<br> This website is <a href="https://github.com/jsdoc3/jsdoc3.github.com">open source</a> and is licensed under the <a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/">
Expand Down
52 changes: 18 additions & 34 deletions about-configuring-jsdoc.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,16 +69,14 @@ <h2 id="configuration-file-formats">Configuration file formats</h2>
<figcaption>JSON configuration file</figcaption><pre class="prettyprint lang-js"><code>{
"plugins": ["plugins/markdown"]
}
</code></pre>
</figure>
</code></pre></figure>
<figure>
<figcaption>JavaScript configuration file</figcaption><pre class="prettyprint lang-js"><code>'use strict';

module.exports = {
plugins: ['plugins/markdown']
};
</code></pre>
</figure>
</code></pre></figure>
<p>For a more comprehensive example of a JSON configuration file, see the file
<a href="https://github.com/jsdoc3/jsdoc/blob/master/conf.json.EXAMPLE"><code>conf.json.EXAMPLE</code></a>.</p>
<h2 id="default-configuration-options">Default configuration options</h2>
Expand All @@ -100,8 +98,7 @@ <h2 id="default-configuration-options">Default configuration options</h2>
"monospaceLinks": false
}
}
</code></pre>
</figure>
</code></pre></figure>
<p>This means:</p>
<ul>
<li>No plugins are loaded (<code>plugins</code>).</li>
Expand All @@ -128,8 +125,7 @@ <h2 id="configuring-plugins">Configuring plugins</h2>
"plugins/summarize"
]
}
</code></pre>
</figure>
</code></pre></figure>
<p>See the <a href="about-plugins.html">plugin reference</a> for further information, and look in <a href="https://github.com/jsdoc3/jsdoc/tree/master/plugins">JSDoc&#39;s <code>plugins</code>
directory</a> for the plugins built into JSDoc.</p>
<p>You can configure the Markdown plugin by adding a <code>markdown</code> object to your configuration file. See
Expand All @@ -141,8 +137,7 @@ <h2 id="specifying-recursion-depth">Specifying recursion depth</h2>
<figure><pre class="prettyprint lang-js"><code>{
"recurseDepth": 10
}
</code></pre>
</figure>
</code></pre></figure>
<h2 id="specifying-input-files">Specifying input files</h2>
<p>The <code>source</code> 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.</p>
Expand All @@ -154,16 +149,15 @@ <h2 id="specifying-input-files">Specifying input files</h2>
"excludePattern": "(^|\\/|\\\\)_"
}
}
</code></pre>
</figure>
</code></pre></figure>
<ul>
<li><code>source.include</code>: 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 <a href="about-commandline.html"><code>-r</code> command-line option</a> to recurse into subdirectories.</li>
<li><code>source.exclude</code>: 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 <code>source.include</code>.</li>
<li><code>source.includePattern</code>: 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 &quot;.+&#92;.js(doc|x)?$&quot;, meaning that only files with the extensions <code>.js</code>, <code>.jsdoc</code>,
and
be processed by JSDoc. By default, this option is set to <code>.+&amp;#92;.js(doc|x)?$</code>, meaning that only files with the extensions <code>.js</code>,
<code>.jsdoc</code>, and
<code>.jsx</code> will be processed.</li>
<li><code>source.excludePattern</code>: 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.
Expand All @@ -188,8 +182,7 @@ <h2 id="specifying-input-files">Specifying input files</h2>
|- a.js
|- ignore.js
|- d.txt
</code></pre>
</figure>
</code></pre></figure>
<p>In addition, suppose your <code>conf.json</code> file looks like this example:</p>
<figure><pre class="prettyprint lang-js"><code>{
"source": {
Expand All @@ -199,17 +192,13 @@ <h2 id="specifying-input-files">Specifying input files</h2>
"excludePattern": "(^|\\/|\\\\)_"
}
}
</code></pre>
</figure>
</code></pre></figure>
<p>If you run <code>jsdoc myProject/c.js -c /path/to/my/conf.json -r</code> from the file containing the
<code>myProject</code> folder, JSDoc will generate documentation for the following files:</p>
<ul>
<li><code>myProject/a.js</code>
</li>
<li><code>myProject/c.js</code>
</li>
<li><code>myProject/lib/a.js</code>
</li>
<li><code>myProject/a.js</code></li>
<li><code>myProject/c.js</code></li>
<li><code>myProject/lib/a.js</code></li>
</ul>
<p>Here&#39;s why:</p>
<ol>
Expand Down Expand Up @@ -238,8 +227,7 @@ <h2 id="specifying-the-source-type">Specifying the source type</h2>
<figure><pre class="prettyprint lang-js"><code>{
"sourceType": "module"
}
</code></pre>
</figure>
</code></pre></figure>
<h2 id="incorporating-command-line-options-into-the-configuration-file">Incorporating command-line options into the configuration file</h2>
<p>You can put many of JSDoc&#39;s <a href="about-commandline.html">command-line options</a> into the configuration file instead of specifying them on the command
line. To do this, add the long names of the relevant options into an
Expand All @@ -254,8 +242,7 @@ <h2 id="incorporating-command-line-options-into-the-configuration-file">Incorpor
"tutorials": "path/to/tutorials", // same as -u path/to/tutorials
}
}
</code></pre>
</figure>
</code></pre></figure>
<p>By using the <code>source.include</code> and <code>opts</code> options, you can put almost all of the arguments to JSDoc in a configuration file, so that the
command line reduces to:</p>
<pre class="prettyprint"><code>jsdoc -c /path/to/conf.json
Expand All @@ -269,8 +256,7 @@ <h2 id="configuring-tags-and-tag-dictionaries">Configuring tags and tag dictiona
"dictionaries": ["jsdoc","closure"]
}
}
</code></pre>
</figure>
</code></pre></figure>
<p>The <code>tags.allowUnknownTags</code> property affects how JSDoc handles unrecognized tags. If you set this option to <code>false</code>, and JSDoc finds a
tag that it does not recognize (for example, <code>@foo</code>), JSDoc logs a warning. By default, this option is set to <code>true</code>. In JSDoc 3.4.1
and later, you can also set this property to an array of tag names that JSDoc should allow (for example, <code>[&quot;foo&quot;,&quot;bar&quot;]</code>).</p>
Expand All @@ -296,8 +282,7 @@ <h2 id="configuring-templates">Configuring templates</h2>
"monospaceLinks": false
}
}
</code></pre>
</figure>
</code></pre></figure>
<p>If <code>templates.monospaceLinks</code> is true, all link text from the <a href="tags-inline-link.html">inline <code>{@link}</code>
tag</a> will be rendered in monospace.</p>
<p>If <code>templates.cleverLinks</code> is true, <code>{@link asdf}</code> will be rendered in normal font if <code>asdf</code> is a URL, and monospace otherwise.
Expand All @@ -318,8 +303,7 @@ <h2 id="related-links">Related Links</h2>
</article>
<footer>
<a class="license-badge" href="http://creativecommons.org/licenses/by-sa/3.0/">
<img alt="Creative Commons License" class="license-badge" src="images/cc-by-sa.svg" width="80" height="15" />
</a>
<img alt="Creative Commons License" class="license-badge" src="images/cc-by-sa.svg" width="80" height="15" /></a>
<br> Copyright &#169; 2011-2017 the
<a href="https://github.com/jsdoc3/jsdoc3.github.com/contributors">contributors</a> to the JSDoc 3 documentation project.
<br> This website is <a href="https://github.com/jsdoc3/jsdoc3.github.com">open source</a> and is licensed under the <a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/">
Expand Down
Loading