chore: added some jsdoc (#2418)

* added some jsdoc

* Update src/helpers.js

Co-authored-by: Tony Brix <tony@brix.ninja>

* Update src/Renderer.js

Co-authored-by: Tony Brix <tony@brix.ninja>

Co-authored-by: Tony Brix <tony@brix.ninja>

bin/marked.js

@@ -188,6 +188,9 @@ function getStdin() {
   });
 }
 
+/**
+ * @param {string} text
+ */
 function camelize(text) {
   return text.replace(/(\w)-(\w)/g, function(_, a, b) {
     return a + b.toUpperCase();

build-docs.js

@@ -3,6 +3,7 @@ import { join, dirname, parse, format } from 'path';
 import { parse as marked } from './lib/marked.esm.js';
 import { HighlightJS } from 'highlight.js';
 import titleize from 'titleize';
+
 const { mkdir, rm, readdir, stat, readFile, writeFile, copyFile } = promises;
 const { highlight, highlightAuto } = HighlightJS;
 const cwd = process.cwd();

src/Lexer.js

@@ -5,6 +5,7 @@ import { repeatString } from './helpers.js';
 
 /**
  * smartypants text replacement
+ * @param {string} text
  */
 function smartypants(text) {
   return text
@@ -26,6 +27,7 @@ function smartypants(text) {
 
 /**
  * mangle email addresses
+ * @param {string} text
  */
 function mangle(text) {
   let out = '',

src/Renderer.js

@@ -38,6 +38,9 @@ export class Renderer {
       + '</code></pre>\n';
   }
 
+  /**
+   * @param {string} quote
+   */
   blockquote(quote) {
     return '<blockquote>\n' + quote + '</blockquote>\n';
   }
@@ -46,6 +49,12 @@ export class Renderer {
     return html;
   }
 
+  /**
+   * @param {string} text
+   * @param {string} level
+   * @param {string} raw
+   * @param {any} slugger
+   */
   heading(text, level, raw, slugger) {
     if (this.options.headerIds) {
       return '<h'
@@ -73,6 +82,9 @@ export class Renderer {
     return '<' + type + startatt + '>\n' + body + '</' + type + '>\n';
   }
 
+  /**
+   * @param {string} text
+   */
   listitem(text) {
     return '<li>' + text + '</li>\n';
   }
@@ -85,10 +97,17 @@ export class Renderer {
       + '> ';
   }
 
+  /**
+   * @param {string} text
+   */
   paragraph(text) {
     return '<p>' + text + '</p>\n';
   }
 
+  /**
+   * @param {string} header
+   * @param {string} body
+   */
   table(header, body) {
     if (body) body = '<tbody>' + body + '</tbody>';
 
@@ -100,6 +119,9 @@ export class Renderer {
       + '</table>\n';
   }
 
+  /**
+   * @param {string} content
+   */
   tablerow(content) {
     return '<tr>\n' + content + '</tr>\n';
   }
@@ -112,15 +134,24 @@ export class Renderer {
     return tag + content + '</' + type + '>\n';
   }
 
-  // span level renderer
+  /**
+   * span level renderer
+   * @param {string} text
+   */
   strong(text) {
     return '<strong>' + text + '</strong>';
   }
 
+  /**
+   * @param {string} text
+   */
   em(text) {
     return '<em>' + text + '</em>';
   }
 
+  /**
+   * @param {string} text
+   */
   codespan(text) {
     return '<code>' + text + '</code>';
   }
@@ -129,10 +160,18 @@ export class Renderer {
     return this.options.xhtml ? '<br/>' : '<br>';
   }
 
+  /**
+   * @param {string} text
+   */
   del(text) {
     return '<del>' + text + '</del>';
   }
 
+  /**
+   * @param {string} href
+   * @param {string} title
+   * @param {string} text
+   */
   link(href, title, text) {
     href = cleanUrl(this.options.sanitize, this.options.baseUrl, href);
     if (href === null) {
@@ -146,6 +185,11 @@ export class Renderer {
     return out;
   }
 
+  /**
+   * @param {string} href
+   * @param {string} title
+   * @param {string} text
+   */
   image(href, title, text) {
     href = cleanUrl(this.options.sanitize, this.options.baseUrl, href);
     if (href === null) {

src/Slugger.js

@@ -6,6 +6,9 @@ export class Slugger {
     this.seen = {};
   }
 
+  /**
+   * @param {string} value
+   */
   serialize(value) {
     return value
       .toLowerCase()
@@ -19,6 +22,8 @@ export class Slugger {
 
   /**
    * Finds the next safe (unique) slug to use
+   * @param {string} originalSlug
+   * @param {boolean} isDryRun
    */
   getNextSafeSlug(originalSlug, isDryRun) {
     let slug = originalSlug;
@@ -39,8 +44,9 @@ export class Slugger {
 
   /**
    * Convert string to unique id
-   * @param {object} options
+   * @param {object} [options]
-   * @param {boolean} options.dryrun Generates the next unique slug without updating the internal accumulator.
+   * @param {boolean} [options.dryrun] Generates the next unique slug without
+   * updating the internal accumulator.
    */
   slug(value, options = {}) {
     const slug = this.serialize(value);

src/helpers.js

@@ -29,6 +29,9 @@ export function escape(html, encode) {
 
 const unescapeTest = /&(#(?:\d+)|(?:#x[0-9A-Fa-f]+)|(?:\w+));?/ig;
 
+/**
+ * @param {string} html
+ */
 export function unescape(html) {
   // explicitly match decimal, hex, and named HTML entities
   return html.replace(unescapeTest, (_, n) => {
@@ -44,8 +47,13 @@ export function unescape(html) {
 }
 
 const caret = /(^|[^\[])\^/g;
+
+/**
+ * @param {string | RegExp} regex
+ * @param {string} opt
+ */
 export function edit(regex, opt) {
-  regex = regex.source || regex;
+  regex = typeof regex === 'string' ? regex : regex.source;
   opt = opt || '';
   const obj = {
     replace: (name, val) => {
@@ -63,6 +71,12 @@ export function edit(regex, opt) {
 
 const nonWordAndColonTest = /[^\w:]/g;
 const originIndependentUrl = /^$|^[a-z][a-z0-9+.-]*:|^[?#]/i;
+
+/**
+ * @param {boolean} sanitize
+ * @param {string} base
+ * @param {string} href
+ */
 export function cleanUrl(sanitize, base, href) {
   if (sanitize) {
     let prot;
@@ -93,6 +107,10 @@ const justDomain = /^[^:]+:\/*[^/]*$/;
 const protocol = /^([^:]+:)[\s\S]*$/;
 const domain = /^([^:]+:\/*[^/]*)[\s\S]*$/;
 
+/**
+ * @param {string} base
+ * @param {string} href
+ */
 export function resolveUrl(base, href) {
   if (!baseUrls[' ' + base]) {
     // we can ignore everything in base after the last slash of its path component,
@@ -177,9 +195,14 @@ export function splitCells(tableRow, count) {
   return cells;
 }
 
-// Remove trailing 'c's. Equivalent to str.replace(/c*$/, '').
+/**
-// /c*$/ is vulnerable to REDOS.
+ * Remove trailing 'c's. Equivalent to str.replace(/c*$/, '').
-// invert: Remove suffix of non-c chars instead. Default falsey.
+ * /c*$/ is vulnerable to REDOS.
+ *
+ * @param {string} str
+ * @param {string} c
+ * @param {boolean} invert Remove suffix of non-c chars instead. Default falsey.
+ */
 export function rtrim(str, c, invert) {
   const l = str.length;
   if (l === 0) {
@@ -233,6 +256,10 @@ export function checkSanitizeDeprecation(opt) {
 }
 
 // copied from https://stackoverflow.com/a/5450113/806777
+/**
+ * @param {string} pattern
+ * @param {number} count
+ */
 export function repeatString(pattern, count) {
   if (count < 1) {
     return '';

src/marked.js

@@ -289,6 +289,7 @@ marked.walkTokens = function(tokens, callback) {
 
 /**
  * Parse Inline
+ * @param {string} src
  */
 marked.parseInline = function(src, opt) {
   // throw error in case of non string input