Refactor code-style

*   Add more docs to JSDoc
*   Add support for `null` in input of API types

Author: wooorm

lib/index.js

@@ -1,14 +1,17 @@
 /**
  * @typedef {import('mdast').Link} Link
+ * @typedef {import('mdast').PhrasingContent} PhrasingContent
+ *
  * @typedef {import('mdast-util-from-markdown').CompileContext} CompileContext
  * @typedef {import('mdast-util-from-markdown').Extension} FromMarkdownExtension
- * @typedef {import('mdast-util-from-markdown').Transform} FromMarkdownTransform
  * @typedef {import('mdast-util-from-markdown').Handle} FromMarkdownHandle
+ * @typedef {import('mdast-util-from-markdown').Transform} FromMarkdownTransform
+ *
  * @typedef {import('mdast-util-to-markdown').ConstructName} ConstructName
- * @typedef {import('mdast-util-to-markdown/lib/types.js').Options} ToMarkdownExtension
+ * @typedef {import('mdast-util-to-markdown').Options} ToMarkdownExtension
+ *
  * @typedef {import('mdast-util-find-and-replace').ReplaceFunction} ReplaceFunction
  * @typedef {import('mdast-util-find-and-replace').RegExpMatchObject} RegExpMatchObject
- * @typedef {import('mdast').PhrasingContent} PhrasingContent
  */
 
 import {ccount} from 'ccount'
@@ -20,7 +23,11 @@ const inConstruct = 'phrasing'
 /** @type {Array<ConstructName>} */
 const notInConstruct = ['autolink', 'link', 'image', 'label']
 
-/** @type {FromMarkdownExtension} */
+/**
+ * Extension for `mdast-util-from-markdown` to enable GFM autolink literals.
+ *
+ * @type {FromMarkdownExtension}
+ */
 export const gfmAutolinkLiteralFromMarkdown = {
   transforms: [transformGfmAutolinkLiterals],
   enter: {
@@ -37,7 +44,11 @@ export const gfmAutolinkLiteralFromMarkdown = {
   }
 }
 
-/** @type {ToMarkdownExtension} */
+/**
+ * Extension for `mdast-util-to-markdown` to enable GFM autolink literals.
+ *
+ * @type {ToMarkdownExtension}
+ */
 export const gfmAutolinkLiteralToMarkdown = {
   unsafe: [
     {
@@ -54,13 +65,7 @@ export const gfmAutolinkLiteralToMarkdown = {
       inConstruct,
       notInConstruct
     },
-    {
-      character: ':',
-      before: '[ps]',
-      after: '\\/',
-      inConstruct,
-      notInConstruct
-    }
+    {character: ':', before: '[ps]', after: '\\/', inConstruct, notInConstruct}
   ]
 }
 
@@ -133,6 +138,7 @@ function transformGfmAutolinkLiterals(tree) {
  * @param {string} domain
  * @param {string} path
  * @param {RegExpMatchObject} match
+ * @returns {Link | Array<PhrasingContent> | false}
  */
 // eslint-disable-next-line max-params
 function findUrl(_, protocol, domain, path, match) {
@@ -158,7 +164,7 @@ function findUrl(_, protocol, domain, path, match) {
 
   if (!parts[0]) return false
 
-  /** @type {PhrasingContent} */
+  /** @type {Link} */
   const result = {
     type: 'link',
     title: null,
@@ -179,6 +185,7 @@ function findUrl(_, protocol, domain, path, match) {
  * @param {string} atext
  * @param {string} label
  * @param {RegExpMatchObject} match
+ * @returns {Link | false}
  */
 function findEmail(_, atext, label, match) {
   if (
@@ -222,40 +229,35 @@ function isCorrectDomain(domain) {
 
 /**
  * @param {string} url
- * @returns {[string, string|undefined]}
+ * @returns {[string, string | undefined]}
  */
 function splitUrl(url) {
   const trailExec = /[!"&'),.:;<>?\]}]+$/.exec(url)
-  /** @type {number} */
-  let closingParenIndex
-  /** @type {number} */
-  let openingParens
-  /** @type {number} */
-  let closingParens
-  /** @type {string|undefined} */
-  let trail
-
-  if (trailExec) {
-    url = url.slice(0, trailExec.index)
-    trail = trailExec[0]
+
+  if (!trailExec) {
+    return [url, undefined]
+  }
+
+  url = url.slice(0, trailExec.index)
+
+  let trail = trailExec[0]
+  let closingParenIndex = trail.indexOf(')')
+  const openingParens = ccount(url, '(')
+  let closingParens = ccount(url, ')')
+
+  while (closingParenIndex !== -1 && openingParens > closingParens) {
+    url += trail.slice(0, closingParenIndex + 1)
+    trail = trail.slice(closingParenIndex + 1)
     closingParenIndex = trail.indexOf(')')
-    openingParens = ccount(url, '(')
-    closingParens = ccount(url, ')')
-
-    while (closingParenIndex !== -1 && openingParens > closingParens) {
-      url += trail.slice(0, closingParenIndex + 1)
-      trail = trail.slice(closingParenIndex + 1)
-      closingParenIndex = trail.indexOf(')')
-      closingParens++
-    }
+    closingParens++
   }
 
   return [url, trail]
 }
 
 /**
  * @param {RegExpMatchObject} match
- * @param {boolean} [email=false]
+ * @param {boolean | null | undefined} [email=false]
  * @returns {boolean}
  */
 function previous(match, email) {