Skip to content

Feature/design updates #138

New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

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

Feature/design updates #138

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1f10367
added modified files
timwright12 Sep 27, 2016
74b221c
Typography refresh, syncing colors and added some ARIA landmark roles
timwright12 Sep 27, 2016
2874de5
quick type fix
timwright12 Sep 27, 2016
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
16 changes: 16 additions & 0 deletions .editorconfig
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
# EditorConfig helps developers define and maintain consistent
# coding styles between different editors and IDEs
# editorconfig.org

root = true

[*]
indent_style = space
indent_size = 4
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = false

[*.md]
trim_trailing_whitespace = false
23 changes: 11 additions & 12 deletions about-block-inline-tags.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,10 +17,13 @@
</head>

<body>
<header>
<a href="./index.html">@use JSDoc</a>
<header role="banner">
<div class="container">
<h1 class="branding"><a href="./index.html">@use JSDoc</a></h1>
</div>
<!--/.container-->
</header>
<article>
<article role="main">
<h1>Block and inline tags</h1>
<h2>Table of Contents</h2>
<ul>
Expand Down Expand Up @@ -55,8 +58,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 +70,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 +82,11 @@ <h2 id="examples">Examples</h2>
Shoe.prototype.setLaceType = function(color, type) {
// ...
};
</code></pre>
</figure>
</code></pre></figure>
</article>
<footer>
<footer role="contentinfo">
<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-2014 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
80 changes: 30 additions & 50 deletions about-commandline.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,10 +17,13 @@
</head>

<body>
<header>
<a href="./index.html">@use JSDoc</a>
<header role="banner">
<div class="container">
<h1 class="branding"><a href="./index.html">@use JSDoc</a></h1>
</div>
<!--/.container-->
</header>
<article>
<article role="main">
<h1>Command-line arguments to JSDoc</h1>
<h2>Table of Contents</h2>
<ul>
Expand Down Expand Up @@ -48,107 +51,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 +140,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 conf.json</a>
</p>
</article>
<footer>
<footer role="contentinfo">
<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-2014 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
14 changes: 8 additions & 6 deletions about-configuring-default-template.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,10 +17,13 @@
</head>

<body>
<header>
<a href="./index.html">@use JSDoc</a>
<header role="banner">
<div class="container">
<h1 class="branding"><a href="./index.html">@use JSDoc</a></h1>
</div>
<!--/.container-->
</header>
<article>
<article role="main">
<h1>Configuring JSDoc&#39;s default template</h1>
<h2>Table of Contents</h2>
<ul>
Expand Down Expand Up @@ -101,10 +104,9 @@ <h2 id="related-links">Related Links</h2>
<a href="about-configuring-jsdoc.html">Configuring JSDoc with conf.json</a>
</p>
</article>
<footer>
<footer role="contentinfo">
<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-2014 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
50 changes: 20 additions & 30 deletions about-configuring-jsdoc.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,10 +17,13 @@
</head>

<body>
<header>
<a href="./index.html">@use JSDoc</a>
<header role="banner">
<div class="container">
<h1 class="branding"><a href="./index.html">@use JSDoc</a></h1>
</div>
<!--/.container-->
</header>
<article>
<article role="main">
<h1>Configuring JSDoc with conf.json</h1>
<h2>Table of Contents</h2>
<ul>
Expand Down Expand Up @@ -65,8 +68,7 @@ <h2 id="configuration-file">Configuration File</h2>
"monospaceLinks": false
}
}
</code></pre>
</figure>
</code></pre></figure>
<p>This means:</p>
<ul>
<li>JSDoc allows you to use unrecognized tags (<code>tags.allowUnknownTags</code>);</li>
Expand All @@ -88,8 +90,7 @@ <h2 id="specifying-input-files">Specifying input files</h2>
"includePattern": ".+\\.js(doc)?$",
"excludePattern": "(^|\\/|\\\\)_"
}
</code></pre>
</figure>
</code></pre></figure>
<ul>
<li><code>source.include</code>: an optional array of paths that JSDoc should generate documentation for. The paths given to JSDoc on the command line are combined
with these to form the set of files JSDoc will scan. Recall that if a path is a directory, the <code>-r</code> option may be used to recurse into it.</li>
Expand Down Expand Up @@ -121,29 +122,23 @@ <h2 id="specifying-input-files">Specifying input files</h2>
|- a.js
|- ignore.js
|- d.txt
</code></pre>
</figure>
</code></pre></figure>
<p>And I set the &quot;source&quot; part of my conf.json like so:</p>
<figure><pre class="prettyprint lang-js"><code>"source": {
"include": [ "myProject/a.js", "myProject/lib", "myProject/_private" ],
"exclude": [ "myProject/lib/ignore.js" ],
"includePattern": ".+\\.js(doc)?$",
"excludePattern": "(^|\\/|\\\\)_"
}
</code></pre>
</figure>
</code></pre></figure>
<p>If I run JSDoc like this from the file containing the <code>myProject</code> folder:</p>
<figure><pre class="prettyprint"><code>jsdoc myProject/c.js -c /path/to/my/conf.json -r
</code></pre>
</figure>
</code></pre></figure>
<p>Then JSDoc will make documentation for the 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>The reasoning is as follows:</p>
<ol>
Expand Down Expand Up @@ -172,8 +167,7 @@ <h2 id="incorporating-command-line-options-into-the-configuration-file">Incorpor
"recurse": true, // same as -r
"tutorials": "path/to/tutorials", // same as -u path/to/tutorials
}
</code></pre>
</figure>
</code></pre></figure>
<p>Hence between <code>source.include</code> and <code>opts</code> it&#39;s possible to put <em>all</em> of jsdoc&#39;s arguments in a configuration file so that
the command-line reduces to:</p>
<pre class="prettyprint"><code>jsdoc -c /path/to/conf.json
Expand All @@ -188,8 +182,7 @@ <h2 id="plugins">Plugins</h2>
"plugins/markdown",
"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 <code>jsdoc/plugins</code> for the plugins built-in to JSDoc.</p>
<p>The Markdown plugin can be configured by including a &quot;markdown&quot; object into conf.json; see
<a href="plugins-markdown.html">Configuring the Markdown Plugin</a> for further information.</p>
Expand All @@ -201,8 +194,7 @@ <h2 id="output-style-configuration">Output style configuration</h2>
"cleverLinks": false,
"monospaceLinks": false
}
</code></pre>
</figure>
</code></pre></figure>
<p>If <code>templates.monospaceLinks</code> is true, all link texts from the <a href="tags-inline-link.html">@link</a> tag will be rendered in monospace.</p>
<p>If <code>templates.cleverLinks</code> is true, {@link asdf} will be rendered in normal font if &quot;asdf&quot; is a URL, and monospace otherwise. For example,
<code>{@link http://github.com}</code> will render in plain-text but
Expand All @@ -215,8 +207,7 @@ <h2 id="tags-and-tag-dictionaries">Tags and tag dictionaries</h2>
"allowUnknownTags": true,
"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 Down Expand Up @@ -245,10 +236,9 @@ <h2 id="related-links">Related Links</h2>
</li>
</ul>
</article>
<footer>
<footer role="contentinfo">
<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-2014 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