Skip to content

Commit

Permalink
docs: generate API ref via jsdoc
Browse files Browse the repository at this point in the history
  • Loading branch information
@benelan
benelan committed Apr 25, 2024
1 parent 6abf1c1 commit ba79d07
Show file tree
Hide file tree
Showing 3 changed files with 162 additions and 115 deletions.
74 changes: 37 additions & 37 deletions docs/global.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -43,8 +43,8 @@ <h4 class="name" id="filterFilesByType">
</h4>

<div class="description">
Filters files by filetype. Use
<a href="global.html#getFiles">getFiles</a> to retrieve your build
Filter files by filetype. Use
<a href="global.html#getFiles">getFiles</a> to retrieve the build
files.
</div>

Expand Down Expand Up @@ -101,7 +101,7 @@ <h5>Parameters:</h5>
<ul class="dummy">
<li>
<a href="index.js.html">index.js</a>,
<a href="index.js.html#line97">line 97</a>
<a href="index.js.html#line105">line 105</a>
</li>
</ul>
</dd>
Expand All @@ -128,7 +128,7 @@ <h4 class="name" id="formatBytes">
><span class="type-signature"> &rarr; {string}</span>
</h4>

<div class="description">Formats bytes to a human readable size.</div>
<div class="description">Format bytes to a human readable size.</div>

<h5>Parameters:</h5>

Expand Down Expand Up @@ -207,7 +207,7 @@ <h5>Parameters:</h5>
<ul class="dummy">
<li>
<a href="index.js.html">index.js</a>,
<a href="index.js.html#line19">line 19</a>
<a href="index.js.html#line30">line 30</a>
</li>
</ul>
</dd>
Expand Down Expand Up @@ -237,7 +237,7 @@ <h4 class="name" id="getBuildSizes">
</h4>

<div class="description">
Provides sizes for an application's build.
Determine metrics related to an application's build size.
</div>

<h5>Parameters:</h5>
Expand Down Expand Up @@ -281,10 +281,10 @@ <h5>Parameters:</h5>

<td class="attributes">&lt;optional><br /></td>

<td class="default">"js"</td>
<td class="default">js</td>

<td class="description last">
type of bundle files, e.g. "js", "css", etc.
file type of bundle, e.g. "js", "css", etc.
</td>
</tr>
</tbody>
Expand All @@ -296,7 +296,7 @@ <h5>Parameters:</h5>
<ul class="dummy">
<li>
<a href="index.js.html">index.js</a>,
<a href="index.js.html#line144">line 144</a>
<a href="index.js.html#line157">line 157</a>
</li>
</ul>
</dd>
Expand Down Expand Up @@ -324,7 +324,7 @@ <h4 class="name" id="getFileSizeBrotli">
</h4>

<div class="description">
Compresses a file using brotli and returns the size.
Compress a file using brotli and return the size.
</div>

<h5>Parameters:</h5>
Expand Down Expand Up @@ -366,7 +366,7 @@ <h5>Parameters:</h5>
<ul class="dummy">
<li>
<a href="index.js.html">index.js</a>,
<a href="index.js.html#line125">line 125</a>
<a href="index.js.html#line137">line 137</a>
</li>
</ul>
</dd>
Expand All @@ -375,7 +375,7 @@ <h5>Parameters:</h5>
<h5>Returns:</h5>

<div class="param-desc">
file size compressed using brotli with the default
brotli-compressed byte size using the default
<a href="https://nodejs.org/api/zlib.html#brotli-constants">zlib</a>
options
</div>
Expand All @@ -395,7 +395,7 @@ <h4 class="name" id="getFileSizeGzip">
</h4>

<div class="description">
Compresses a file using gzip and returns the size.
Compress a file using gzip and return the size.
</div>

<h5>Parameters:</h5>
Expand Down Expand Up @@ -437,7 +437,7 @@ <h5>Parameters:</h5>
<ul class="dummy">
<li>
<a href="index.js.html">index.js</a>,
<a href="index.js.html#line106">line 106</a>
<a href="index.js.html#line116">line 116</a>
</li>
</ul>
</dd>
Expand All @@ -446,8 +446,8 @@ <h5>Parameters:</h5>
<h5>Returns:</h5>

<div class="param-desc">
file size compressed using gzip with the default
<a href="https://nodejs.org/api/zlib.html#class-options">zlib</a>
gzip-compressed byte size using the default
<a href="https://nodejs.org/api/zlib.html#brotli-constants">zlib</a>
options
</div>

Expand All @@ -461,15 +461,15 @@ <h5>Returns:</h5>
<h4 class="name" id="getFiles">
<span class="type-signature">(async) </span>getFiles<span
class="signature"
>(directoryPath)</span
>(parentDir)</span
><span class="type-signature">
&rarr; {Promise.&lt;Array.&lt;<a href="global.html#File">File</a
>>>}</span
>
</h4>

<div class="description">
Returns all files in a directory (recursive).
Find sizes of all files in a directory (recursive).
</div>

<h5>Parameters:</h5>
Expand All @@ -487,7 +487,7 @@ <h5>Parameters:</h5>

<tbody>
<tr>
<td class="name"><code>directoryPath</code></td>
<td class="name"><code>parentDir</code></td>

<td class="type">
<span class="param-type">string</span>
Expand All @@ -513,7 +513,7 @@ <h5>Parameters:</h5>
<ul class="dummy">
<li>
<a href="index.js.html">index.js</a>,
<a href="index.js.html#line51">line 51</a>
<a href="index.js.html#line66">line 66</a>
</li>
</ul>
</dd>
Expand Down Expand Up @@ -543,9 +543,10 @@ <h4 class="name" id="saveBuildSizes">
</h4>

<div class="description">
Saves the build sizes from
Save the results from
<a href="global.html#getBuildSizes">getBuildSizes</a> to a CSV file.
Useful for tracking sizes over time.
Useful for tracking build sizes over time, e.g., in a CI/CD
pipeline.
</div>

<h5>Parameters:</h5>
Expand Down Expand Up @@ -584,7 +585,7 @@ <h5>Parameters:</h5>
</td>

<td class="description last">
the path to the output file, e.g. data/build-sizes.csv
path of the output file, e.g. build/size.csv
</td>
</tr>
</tbody>
Expand All @@ -603,7 +604,7 @@ <h5>Parameters:</h5>
<ul class="dummy">
<li>
<a href="index.js.html">index.js</a>,
<a href="index.js.html#line208">line 208</a>
<a href="index.js.html#line223">line 223</a>
</li>
</ul>
</dd>
Expand All @@ -614,14 +615,13 @@ <h3 class="subsection-title">Type Definitions</h3>
<h4 class="name" id="BuildSizes">BuildSizes</h4>

<div class="description">
Information about a project's build sizes, primarily used for
optimization.
Information about an application's build sizes.
</div>

<h5>Type:</h5>
<ul>
<li>
<span class="param-type">Object</span>
<span class="param-type">object</span>
</li>
</ul>

Expand Down Expand Up @@ -659,7 +659,7 @@ <h5 class="subsection-title">Properties:</h5>
</td>

<td class="description last">
size in bytes of the largest bundle file by type
byte size of the largest bundle file by type
</td>
</tr>

Expand All @@ -671,7 +671,7 @@ <h5 class="subsection-title">Properties:</h5>
</td>

<td class="description last">
size in bytes of the main bundle file compressed with gzip
gzip-compressed byte size of the main bundle file
</td>
</tr>

Expand All @@ -683,7 +683,7 @@ <h5 class="subsection-title">Properties:</h5>
</td>

<td class="description last">
size in bytes of the main bundle file compressed with brotli
brotli-compressed byte size of the main bundle file
</td>
</tr>

Expand All @@ -695,7 +695,7 @@ <h5 class="subsection-title">Properties:</h5>
</td>

<td class="description last">
size in bytes of all files in the build directory
byte size of all files in the build directory
</td>
</tr>

Expand Down Expand Up @@ -732,7 +732,7 @@ <h5 class="subsection-title">Properties:</h5>
<ul class="dummy">
<li>
<a href="index.js.html">index.js</a>,
<a href="index.js.html#line288">line 288</a>
<a href="index.js.html#line310">line 310</a>
</li>
</ul>
</dd>
Expand All @@ -749,12 +749,12 @@ <h5 class="subsection-title">Properties:</h5>

<h4 class="name" id="File">File</h4>

<div class="description">Important information about a file.</div>
<div class="description">Information about a file.</div>

<h5>Type:</h5>
<ul>
<li>
<span class="param-type">Object</span>
<span class="param-type">object</span>
</li>
</ul>

Expand Down Expand Up @@ -810,7 +810,7 @@ <h5 class="subsection-title">Properties:</h5>
<ul class="dummy">
<li>
<a href="index.js.html">index.js</a>,
<a href="index.js.html#line276">line 276</a>
<a href="index.js.html#line297">line 297</a>
</li>
</ul>
</dd>
Expand Down Expand Up @@ -856,8 +856,8 @@ <h3>Global</h3>

<footer>
Documentation generated by
<a href="https://github.com/jsdoc/jsdoc">JSDoc 4.0.2</a> on Thu Jul 13
2023 18:34:29 GMT-0700 (Pacific Daylight Time)
<a href="https://github.com/jsdoc/jsdoc">JSDoc 4.0.2</a> on Thu Apr 25
2024 05:02:04 GMT-0700 (Pacific Daylight Time)
</footer>

<script>
Expand Down
54 changes: 39 additions & 15 deletions docs/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,14 +40,14 @@ <h2>Installation</h2>
<a href="https://www.npmjs.com/package/build-sizes">the package</a>
globally and use it anywhere:
</p>
<pre class="prettyprint source lang-bash"><code>npm i -g build-sizes
<pre class="prettyprint source lang-sh"><code>npm i -g build-sizes
</code></pre>
<p>Use it in a single application:</p>
<pre class="prettyprint source lang-bash"><code>npm i -D build-sizes
<pre class="prettyprint source lang-sh"><code>npm i -D build-sizes
</code></pre>
<p>Or try it out before installing:</p>
<pre
class="prettyprint source lang-bash"
class="prettyprint source lang-sh"
><code>npx build-sizes your/build/directory
</code></pre>
<br />
Expand All @@ -61,7 +61,7 @@ <h2>Using the CLI</h2>
application, you can get the sizes by running the following from the
application's root directory:
</p>
<pre class="prettyprint source lang-bash"><code>build-sizes build
<pre class="prettyprint source lang-sh"><code>build-sizes build
</code></pre>
<p>And the output to the console is:</p>
<pre
Expand All @@ -80,18 +80,45 @@ <h2>Using the CLI</h2>
--> brotli size: 375.26 KB
-----------------------------
</code></pre>
<blockquote>
<p>
<strong>NOTE:</strong> The &quot;main bundle&quot; file is naively
chosen by largest file size, it doesn't use a dependency graph.
This script is minimal by design, check out
<a
href="https://github.com/webpack-contrib/webpack-bundle-analyzer"
><code>webpack-bundle-analyzer</code></a
>
for a more complex bundle size tool.
</p>
</blockquote>
<p>
Flags are provided to change the default options. For example, you
can specify a filetype for the largest bundle size (default is
&quot;js&quot;):
</p>
<pre
class="prettyprint source lang-bash"
><code>build-sizes build --filetype=css
class="prettyprint source lang-sh"
><code>build-sizes dist --filetype=css
</code></pre>
<p>
Providing the <code>-h</code> or <code>--help</code> flag will log
usage information to the console, copy/pasted here for convenience:
The argument parsing logic is very simple and requires the equals
sign (<code>=</code>) between the flag and its value. Additionally,
short flags cannot be grouped together into a single argument. Here
are a couple examples of what will and won't work:
</p>
<pre
class="prettyprint source lang-sh"
><code># These two are incorrect
build-sizes dist -lb # -l and -b flags combined into a single argument
build-sizes dist --decimals 4 # space between --decimals flag and its value

# This one is correct
build-sizes dist -l -b --decimals=4
</code></pre>
<p>
The <code>-h</code> or <code>--help</code> flag will log usage
information to the console, copy/pasted here for convenience:
</p>
<details>
<summary>Usage info</summary>
Expand All @@ -103,10 +130,7 @@ <h3>Arguments</h3>
<h3>Options</h3>
<p><strong>-l, --loader [boolean]</strong></p>
<ul>
<li>
Show a loading animation while determining the build size
(doesn't work when executed via npx)
</li>
<li>Show a loading animation while determining the build size</li>
</ul>
<p><strong>-b, --binary [boolean]</strong></p>
<ul>
Expand Down Expand Up @@ -254,7 +278,7 @@ <h2>Using the functions</h2>
directory and output CSV file:
</p>
<pre
class="prettyprint source lang-bash"
class="prettyprint source lang-sh"
><code>node save.js dist sizes.csv
</code></pre>
<p>
Expand Down Expand Up @@ -308,8 +332,8 @@ <h3>Global</h3>

<footer>
Documentation generated by
<a href="https://github.com/jsdoc/jsdoc">JSDoc 4.0.2</a> on Thu Jul 13
2023 18:34:29 GMT-0700 (Pacific Daylight Time)
<a href="https://github.com/jsdoc/jsdoc">JSDoc 4.0.2</a> on Thu Apr 25
2024 05:02:04 GMT-0700 (Pacific Daylight Time)
</footer>

<script>
Expand Down
Loading

0 comments on commit ba79d07

Please sign in to comment.