Merge pull request #33 from remarkablemark/chore/types

chore: update JSDoc and type declaration files
remarkablemark · Dec 8, 2020 · a682d6a · a682d6a
2 parents 375bd37 + a1d0174
commit a682d6a
Show file tree

Hide file tree

Showing 12 changed files with 68 additions and 62 deletions.
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -22,6 +22,7 @@ To check an item, place an "x" in the box like so: `- [x] Tests`
 -->
 
 - [ ] Tests
+- [ ] Types
 - [ ] Documentation
 
 <!--

diff --git a/index.d.ts b/index.d.ts
@@ -1,4 +1,3 @@
-// TypeScript Version: 3.3
+// TypeScript Version: 4.1
 
-import htmlToDomServer from './lib/html-to-dom-server';
-export default htmlToDomServer;
+export { default } from './lib/html-to-dom-server';
diff --git a/lib/constants.d.ts b/lib/constants.d.ts
@@ -1,4 +1,4 @@
-// TypeScript Version: 3.3
+// TypeScript Version: 4.1
 
 /**
  * SVG elements, unlike HTML elements, are case-sensitive.

diff --git a/lib/domparser.d.ts b/lib/domparser.d.ts
@@ -1,9 +1,9 @@
-// TypeScript Version: 3.3
+// TypeScript Version: 4.1
 
 /**
  * Parses HTML string to DOM nodes.
  *
- * @param - Raw string of HTML to parse.
- * @returns NodeList or empty array.
+ * @param  - HTML markup.
+ * @return - NodeList.
  */
-export default function parseDOM(html: string): NodeList | [];
+export default function domparser(html: string): NodeList;
diff --git a/lib/domparser.js b/lib/domparser.js
@@ -123,8 +123,8 @@ if (template.content) {
 /**
  * Parses HTML string to DOM nodes.
  *
- * @param  {string} html - The HTML string.
- * @return {NodeList|Array}
+ * @param  {string}   html - HTML markup.
+ * @return {NodeList}
  */
 function domparser(html) {
   var firstTagName;

diff --git a/lib/html-to-dom-client.d.ts b/lib/html-to-dom-client.d.ts
@@ -1,11 +1,11 @@
-// TypeScript Version: 3.3
+// TypeScript Version: 4.1
 
 import { DomElement } from 'domhandler';
 
 /**
- * Parses HTML and reformats DOM nodes output.
+ * Parses HTML string to DOM nodes in browser.
  *
- * @param - Raw string of HTML to parse.
- * @returns Parsed DomElements.
+ * @param  - HTML markup.
+ * @return - DOM elements.
  */
-export default function parseDOM(html: string): DomElement[];
+export default function HTMLDOMParser(html: string): DomElement[];
diff --git a/lib/html-to-dom-client.js b/lib/html-to-dom-client.js
@@ -9,8 +9,8 @@ var DIRECTIVE_REGEX = /<(![a-zA-Z\s]+)>/; // e.g., <!doctype html>
 /**
  * Parses HTML string to DOM nodes in browser.
  *
- * @param  {String} html - HTML string.
- * @return {Object[]}    - DOM nodes.
+ * @param  {String} html  - HTML markup.
+ * @return {DomElement[]} - DOM elements.
  */
 function HTMLDOMParser(html) {
   if (typeof html !== 'string') {

diff --git a/lib/html-to-dom-server.d.ts b/lib/html-to-dom-server.d.ts
@@ -1,16 +1,18 @@
-// TypeScript Version: 3.3
-
-import { DomHandlerOptions, DomElement } from 'domhandler';
-
-/**
- * Parses HTML string to DOM nodes (server).
- *
- * @remarks
- * This is the same method as `require('htmlparser2').parseDOM`
- * https://github.com/fb55/htmlparser2/blob/v3.9.1/lib/index.js#L39-L43
- *
- * @param - Raw string of HTML to parse.
- * @param - Options to pass to domhandler (See https://github.com/fb55/DomHandler#readme).
- * @returns Parsed DomElements.
- */
-export default function parseDOM(html: string, options?: DomHandlerOptions): DomElement[];
+// TypeScript Version: 4.1
+
+import { DomHandlerOptions, DomElement } from 'domhandler';
+
+/**
+ * Parses HTML string to DOM nodes in Node.js.
+ *
+ * This is the same method as `require('htmlparser2').parseDOM`
+ * https://github.com/fb55/htmlparser2/blob/v3.9.1/lib/index.js#L39-L43
+ *
+ * @param  - HTML markup.
+ * @param  - Parser options (https://github.com/fb55/domhandler/tree/v2.4.2#readme).
+ * @return - DOM elements.
+ */
+export default function HTMLDOMParser(
+  html: string,
+  options?: DomHandlerOptions
+): DomElement[];
diff --git a/lib/html-to-dom-server.js b/lib/html-to-dom-server.js
@@ -7,9 +7,9 @@ var DomHandler = require('domhandler');
  * This is the same method as `require('htmlparser2').parseDOM`
  * https://github.com/fb55/htmlparser2/blob/v3.9.1/lib/index.js#L39-L43
  *
- * @param  {String} html      - HTML string.
- * @param  {Object} [options] - Parser options.
- * @return {DomElement[]}     - DOM nodes.
+ * @param  {String} html      - HTML markup.
+ * @param  {Object} [options] - Parser options (https://github.com/fb55/domhandler/tree/v2.4.2#readme).
+ * @return {DomElement[]}     - DOM elements.
  */
 function HTMLDOMParser(html, options) {
   if (typeof html !== 'string') {

diff --git a/lib/utilities.d.ts b/lib/utilities.d.ts
@@ -1,28 +1,35 @@
-// TypeScript Version: 3.3
+// TypeScript Version: 4.1
 
 import { DomElement } from 'domhandler';
 
 /**
  * Formats DOM attributes to a hash map.
  *
- * @param attributes - The list of attributes to format.
- * @returns - A map of attribute name to value.
+ * @param  attributes - List of attributes.
+ * @return            - Map of attribute name to value.
  */
-export function formatAttributes(attributes: NamedNodeMap): {[name: string]: string};
+export function formatAttributes(
+  attributes: NamedNodeMap
+): { [name: string]: string };
 
 /**
  * Formats the browser DOM nodes to mimic the output of `htmlparser2.parseDOM()`.
  *
- * @param nodes - The DOM nodes to format.
- * @param parentObj - The formatted parent node of the given DOM nodes.
- * @param directive - The directive.
+ * @param  nodes      - DOM nodes.
+ * @param  parentNode - Formatted parent node.
+ * @param  directive  - Directive.
+ * @return            - DOM elements.
  */
-export function formatDOM(nodes: NodeList, parentObj?: DomElement, directive?: string): DomElement[];
+export function formatDOM(
+  nodes: NodeList,
+  parentNode?: DomElement,
+  directive?: string
+): DomElement[];
 
 /**
- * Detects IE with or without version.
+ * Detects if browser is Internet Explorer.
  *
- * @param version - The IE version to detect.
- * @returns - Whether IE or the version has been detected.
+ * @param  version - IE version to detect.
+ * @return         - Whether IE or the version is detected.
  */
 export function isIE(version?: number): boolean;
diff --git a/lib/utilities.js b/lib/utilities.js
@@ -10,8 +10,8 @@ for (var i = 0, len = CASE_SENSITIVE_TAG_NAMES.length; i < len; i++) {
 /**
  * Gets case-sensitive tag name.
  *
- * @param {String} tagName - Tag name in lowercase.
- * @return {String|undefined}
+ * @param  {string}           tagName - Tag name in lowercase.
+ * @return {string|undefined}         - Case-sensitive tag name.
  */
 function getCaseSensitiveTagName(tagName) {
   return caseSensitiveTagNamesMap[tagName];
@@ -20,8 +20,8 @@ function getCaseSensitiveTagName(tagName) {
 /**
  * Formats DOM attributes to a hash map.
  *
- * @param  {NamedNodeMap} attributes - The list of attributes.
- * @return {Object}                  - A map of attribute name to value.
+ * @param  {NamedNodeMap} attributes - List of attributes.
+ * @return {object}                  - Map of attribute name to value.
  */
 function formatAttributes(attributes) {
   var result = {};
@@ -38,8 +38,8 @@ function formatAttributes(attributes) {
  * Corrects the tag name if it is case-sensitive (SVG).
  * Otherwise, returns the lowercase tag name (HTML).
  *
- * @param  {String} tagName - The lowercase tag name.
- * @return {String}         - The formatted tag name.
+ * @param  {string} tagName - Lowercase tag name.
+ * @return {string}         - Formatted tag name.
  */
 function formatTagName(tagName) {
   tagName = tagName.toLowerCase();
@@ -53,10 +53,10 @@ function formatTagName(tagName) {
 /**
  * Formats the browser DOM nodes to mimic the output of `htmlparser2.parseDOM()`.
  *
- * @param  {NodeList} nodes        - DOM nodes.
- * @param  {Object}   [parentNode] - Formatted parent node.
- * @param  {String}   [directive]  - Directive.
- * @return {Object[]}              - Formatted DOM object.
+ * @param  {NodeList}     nodes        - DOM nodes.
+ * @param  {object}       [parentNode] - Formatted parent node.
+ * @param  {string}       [directive]  - Directive.
+ * @return {DomElement[]}              - Formatted DOM object.
  */
 function formatDOM(nodes, parentNode, directive) {
   parentNode = parentNode || null;
@@ -143,8 +143,8 @@ function formatDOM(nodes, parentNode, directive) {
 /**
  * Detects if browser is Internet Explorer.
  *
- * @param {Number} [version] - IE version to detect.
- * @return {Boolean}
+ * @param  {number}  [version] - IE version to detect.
+ * @return {boolean}           - Whether IE or the version is detected.
  */
 function isIE(version) {
   if (version) {

diff --git a/tslint.json b/tslint.json