jsdoc improvement

src/htmlminifier.js

@@ -7,6 +7,160 @@ import { HTMLParser, endTag } from './htmlparser.js';
 import TokenChain from './tokenchain.js';
 import { replaceAsync } from './utils.js';
 
+
+/**
+ * @typedef {Object} MinifyOptions
+ *
+ * Treat attributes in case sensitive manner (useful for custom HTML tags)
+ * @property {boolean} [caseSensitive=false]
+ *
+ * Omit attribute values from boolean attributes
+ * @property {boolean} [collapseBooleanAttributes=false]
+ *
+ * Don't leave any spaces between display:inline; elements when collapsing.
+ * Must be used in conjunction with collapseWhitespace=true
+ * @property {boolean} [collapseInlineTagWhitespace=false]
+ *
+ * Collapse white space that contributes to text nodes in a document tree
+ * @see http://perfectionkills.com/experimenting-with-html-minifier/#collapse_whitespace
+ * @property {boolean} [collapseWhitespace=false]
+ *
+ * Always collapse to 1 space (never remove it entirely). Must be used in
+ * conjunction with collapseWhitespace=true
+ * @property {boolean} [conservativeCollapse=false]
+ *
+ * Handle parse errors instead of aborting
+ * @property {boolean} [continueOnParseError=false]
+ *
+ * Arrays of regex'es that allow to support custom attribute assign expressions
+ * (e.g. '<div flex?="{{mode != cover}}"></div>')
+ * @property {RegExp[]} [customAttrAssign]
+ *
+ * Regex that specifies custom attribute to strip newlines from (e.g. /ng-class/)
+ * @property {RegExp} [customAttrCollapse]
+ *
+ * Arrays of regex'es that allow to support custom attribute surround expressions
+ * (e.g. <input {{#if value}}checked="checked"{{/if}}>)
+ * @property {RegExp[]} [customAttrSurround]
+ *
+ * Arrays of regex'es that allow to support custom event attributes for
+ * minifyJS (e.g. ng-click)
+ * @property {RegExp[]} [customEventAttributes]
+ *
+ * Use direct Unicode characters whenever possible
+ * @property {boolean} [decodeEntities=false]
+ *
+ * Parse input according to HTML5 specifications
+ * @property {boolean} [html5=false]
+ *
+ * Array of regex'es that allow to ignore certain comments, when matched
+ * @property {RegExp[]} [ignoreCustomComments]
+ *
+ * Array of regex'es that allow to ignore certain fragments, when matched
+ * (e.g. <?php ... ?>, {{ ... }}, etc.)
+ * @property {RegExp[]} [ignoreCustomFragments]
+ *
+ * Insert tags generated by HTML parser
+ * @property {boolean} [includeAutoGeneratedTags=false]
+ *
+ * Keep the trailing slash on singleton elements
+ * @property {boolean} [keepClosingSlash=false]
+ *
+ * Specify a maximum line length. Compressed output will be split by newlines at
+ * valid HTML split-points
+ * @property {number} [maxLineLength=0]
+ *
+ * Minify CSS in style elements and style attributes
+ * (uses clean-css or function specified)
+ * @property {boolean|CleanCSS.Options|function(string):string} [minifyCSS=false]
+ *
+ * Minify JavaScript in script elements and event attributes
+ * (uses UglifyJS or function specified)
+ * @property {boolean|UglifyJS.MinifyOptions|function(string, boolean):string} [minifyJS=false]
+ *
+ * Minify URLs in various attributes (uses relateurl or function specified)
+ * @property {boolean|RelateUrl.Options|function(string):string} [minifyURLs=false]
+ *
+ * Always collapse to 1 line break (never remove it entirely) when whitespace
+ * between tags include a line break. Must be used in conjunction with
+ * collapseWhitespace=true
+ * @property {boolean} [preserveLineBreaks=false]
+ *
+ * Prevents the escaping of the values of attributes
+ * @property {boolean} [preventAttributesEscaping=false]
+ *
+ * Process contents of conditional comments through minifier
+ * @property {boolean} [processConditionalComments=false]
+ *
+ * Array of strings corresponding to types of script elements to process through
+ * minifier (e.g. text/ng-template, text/x-handlebars-template, etc.)
+ * @property {string[]} [processScripts]
+ *
+ * Type of quote to use for attribute values (' or ")
+ * @property {string} [quoteCharacter='"']
+ *
+ * Remove quotes around attributes when possible
+ * @see http://perfectionkills.com/experimenting-with-html-minifier/#remove_attribute_quotes
+ * @property {boolean} [removeAttributeQuotes=false]
+ *
+ * Strip HTML comments
+ * @see http://perfectionkills.com/experimenting-with-html-minifier/#remove_comments
+ * @property {boolean} [removeComments=false]
+ *
+ * Remove all attributes with whitespace-only values
+ * @see http://perfectionkills.com/experimenting-with-html-minifier/#remove_empty_or_blank_attributes
+ * @property {boolean | ((attrName: string, tag: string) => boolean)} [removeEmptyAttributes=false]
+ *
+ * Remove all elements with empty contents
+ * @see http://perfectionkills.com/experimenting-with-html-minifier/#remove_empty_elements
+ * @property {boolean} [removeEmptyElements=false]
+ *
+ * Remove optional tags
+ * @see http://perfectionkills.com/experimenting-with-html-minifier/#remove_optional_tags
+ * @property {boolean} [removeOptionalTags=false]
+ *
+ * Remove attributes when value matches default.
+ * @see http://perfectionkills.com/experimenting-with-html-minifier/#remove_redundant_attributes
+ * @property {boolean} [removeRedundantAttributes=false]
+ *
+ * Remove type="text/javascript" from script tags. Other type attribute values
+ * are left intact
+ * @property {boolean} [removeScriptTypeAttributes=false]
+ *
+ * Remove type="text/css" from style and link tags. Other type attribute values
+ * are left intact
+ * @property {boolean} [removeStyleLinkTypeAttributes=false]
+ *
+ * Remove space between attributes whenever possible. Note that this will result
+ * in invalid HTML!
+ * @property {boolean} [removeTagWhitespace=false]
+ *
+ * Sort attributes by frequency
+ *
+ * Minifier options like sortAttributes and sortClassName won't impact the plain-text size
+ * of the output. However, they form long repetitive chains of characters that should improve
+ * compression ratio of gzip used in HTTP compression.
+ *
+ * @see https://github.com/kangax/html-minifier#sorting-attributes--style-classes
+ * @property {boolean} [sortAttributes=false]
+ *
+ * Sort style classes by frequency
+ *
+ * Minifier options like sortAttributes and sortClassName won't impact the plain-text size
+ * of the output. However, they form long repetitive chains of characters that should improve
+ * compression ratio of gzip used in HTTP compression.
+ *
+ * @see https://github.com/kangax/html-minifier#sorting-attributes--style-classes
+ * @property {boolean} [sortClassName=false]
+ *
+ * Trim white space around ignoreCustomFragments
+ * @property {boolean} [trimCustomFragments=false]
+ *
+ * Replaces the doctype with the short (HTML5) doctype
+ * @see http://perfectionkills.com/experimenting-with-html-minifier/#use_short_doctype
+ * @property {boolean} [useShortDoctype=false]
+ */
+
 function trimWhitespace(str) {
   return str && str.replace(/^[ \n\r\t\f]+/, '').replace(/[ \n\r\t\f]+$/, '');
 }
@@ -634,11 +788,12 @@ function identityAsync(value) {
   return Promise.resolve(value);
 }
 
+/**
+ * @param {MinifyOptions} inputOptions
+ */
 const processOptions = (inputOptions) => {
   const options = {
-    name: function (name) {
-      return name.toLowerCase();
-    },
+    name: (name) => name.toLowerCase(),
     canCollapseWhitespace,
     canTrimWhitespace,
     html5: true,
@@ -1355,11 +1510,16 @@ function joinResultSegments(results, options, restoreCustom, restoreIgnore) {
   return options.collapseWhitespace ? collapseWhitespace(str, options, true, true) : str;
 }
 
-export const minify = async function (value, options) {
+/**
+ * @param {*} value
+ * @param {MinifyOptions} options
+ * @returns {Promise<string>}
+ */
+export async function minify (value, options = {}) {
   const start = Date.now();
-  options = processOptions(options || {});
+  options = processOptions(options);
   const result = await minifyHTML(value, options);
-  options.log('minified in: ' + (Date.now() - start) + 'ms');
+  options.log(`minified in: ${Date.now() - start} ms`);
   return result;
 };