doc: clanup annotations

src/markdownit.ts

@@ -291,9 +291,6 @@ class MarkdownIt {
    * containing rules with given names. If rule not found, and `ignoreInvalid`
    * not set - throws exception.
    *
-   * @param list Rule name or list of rule names to enable.
-   * @param ignoreInvalid Set `true` to ignore errors when rule not found.
-   *
    * @example
    * ```javascript
    * import MarkdownIt from 'markdown-it'
@@ -326,9 +323,6 @@ class MarkdownIt {
 
   /**
    * The same as {@link MarkdownIt.enable}, but turn specified rules off.
-   *
-   * @param list Rule name or list of rule names to disable.
-   * @param ignoreInvalid Set `true` to ignore errors when rule not found.
    */
   disable (list: string | string[], ignoreInvalid = false): this {
     let result: string[] = []
@@ -383,9 +377,6 @@ class MarkdownIt {
    * metadata like reference info, needed for the renderer. It also can be used to
    * inject data in specific cases. Usually, you will be ok to pass `{}`,
    * and then pass updated object to renderer.
-   *
-   * @param src Source string.
-   * @param env Environment sandbox.
    */
   parse (src: string, env: Env): Token[] {
     if (typeof src !== 'string') {
@@ -405,9 +396,6 @@ class MarkdownIt {
    * `env` can be used to inject additional metadata (`{}` by default).
    * But you will not need it with high probability. See also comment
    * in {@link MarkdownIt.parse}.
-   *
-   * @param src Source string.
-   * @param env Environment sandbox.
    */
   render (src: string, env: Env = {}): string {
     return this.renderer.render(this.parse(src, env), this.options, env)
@@ -417,9 +405,6 @@ class MarkdownIt {
    * The same as {@link MarkdownIt.parse} but skip all block rules. It returns
    * the block tokens list with the single `inline` element, containing parsed
    * inline tokens in `children` property. Also updates `env` object.
-   *
-   * @param src Source string.
-   * @param env Environment sandbox.
    */
   parseInline (src: string, env: Env): Token[] {
     const state = new this.core.State(src, this, env)
@@ -433,9 +418,6 @@ class MarkdownIt {
   /**
    * Similar to {@link MarkdownIt.render} but for single paragraph content.
    * Result will NOT be wrapped into `<p>` tags.
-   *
-   * @param src Source string.
-   * @param env Environment sandbox.
    */
   renderInline (src: string, env: Env = {}): string {
     return this.renderer.render(this.parseInline(src, env), this.options, env)

src/renderer.ts

@@ -192,10 +192,6 @@ class Renderer {
   /**
    * Default token renderer. Can be overriden by custom function
    * in {@link Renderer.rules}.
-   *
-   * @param tokens List of tokens.
-   * @param idx Token index to render.
-   * @param options Params of parser instance.
    */
   renderToken (tokens: Token[], idx: number, options: Required<MarkdownItOptions>): string {
     const token = tokens[idx]
@@ -269,10 +265,6 @@ class Renderer {
 
   /**
    * The same as {@link Renderer.render}, but for single token of `inline` type.
-   *
-   * @param tokens List on block tokens to render.
-   * @param options Params of parser instance.
-   * @param env Additional data from parsed input (references, for example).
    */
   renderInline (tokens: Token[], options: Required<MarkdownItOptions>, env: Env | undefined): string {
     let result = ''
@@ -295,10 +287,6 @@ class Renderer {
    * Special kludge for image `alt` attributes to conform CommonMark spec.
    * Don't try to use it! Spec requires to show `alt` content with stripped markup,
    * instead of simple escaping.
-   *
-   * @param tokens List on block tokens to render.
-   * @param options Params of parser instance.
-   * @param env Additional data from parsed input (references, for example).
    */
   renderInlineAsText (tokens: Token[], options: Required<MarkdownItOptions>, env: Env | undefined): string {
     let result = ''
@@ -332,10 +320,6 @@ class Renderer {
   /**
    * Takes token stream and generates HTML. Probably, you will never need to call
    * this method directly.
-   *
-   * @param tokens List on block tokens to render.
-   * @param options Params of parser instance.
-   * @param env Additional data from parsed input (references, for example).
    */
   render (tokens: Token[], options: Required<MarkdownItOptions>, env?: Env): string {
     let result = ''

src/ruler.ts

@@ -17,15 +17,7 @@ type RuleOptions = { alt?: string[] }
  * {@link MarkdownIt.use}.
  */
 class Ruler<Args extends unknown[], Result> {
-  // List of added rules. Each element is:
-  //
-  // {
-  //   name: XXX,
-  //   enabled: Boolean,
-  //   fn: Function(),
-  //   alt: [ name2, name3 ]
-  // }
-  //
+  /** @internal */
   __rules__: Array<{
     name: string
     enabled: boolean
@@ -38,12 +30,10 @@ class Ruler<Args extends unknown[], Result> {
   // First level - chain name, '' for default.
   // Second level - diginal anchor for fast filtering by charcodes.
   //
+  /** @internal */
   __cache__: Record<string, Array<(...args: Args) => Result>> | null = null
 
-  // Helper methods, should not be used directly
-
-  // Find rule index by name
-  //
+  /** @internal */
   __find__ (name: string): number {
     for (let i = 0; i < this.__rules__.length; i++) {
       if (this.__rules__[i].name === name) {
@@ -53,8 +43,7 @@ class Ruler<Args extends unknown[], Result> {
     return -1
   }
 
-  // Build rules lookup cache
-  //
+  /** @internal */
   __compile__ (): void {
     const chains = new Set<string>()
 
@@ -90,11 +79,6 @@ class Ruler<Args extends unknown[], Result> {
    * Replace rule by name with new function & options. Throws error if name not
    * found.
    *
-   * @param name Rule name to replace.
-   * @param fn New rule function.
-   * @param options Rule options. `alt` is an array with names of "alternate"
-   * chains.
-   *
    * @example Replace existing typographer replacement rule with new one
    * ```javascript
    * import MarkdownIt from 'markdown-it'
@@ -119,12 +103,6 @@ class Ruler<Args extends unknown[], Result> {
    * Add new rule to chain before one with given name. See also
    * {@link Ruler.after}, {@link Ruler.push}.
    *
-   * @param beforeName New rule will be added before this one.
-   * @param ruleName Name of added rule.
-   * @param fn Rule function.
-   * @param options Rule options. `alt` is an array with names of "alternate"
-   * chains.
-   *
    * @example
    * ```javascript
    * import MarkdownIt from 'markdown-it'
@@ -154,12 +132,6 @@ class Ruler<Args extends unknown[], Result> {
    * Add new rule to chain after one with given name. See also
    * {@link Ruler.before}, {@link Ruler.push}.
    *
-   * @param afterName New rule will be added after this one.
-   * @param ruleName Name of added rule.
-   * @param fn Rule function.
-   * @param options Rule options. `alt` is an array with names of "alternate"
-   * chains.
-   *
    * @example
    * ```javascript
    * import MarkdownIt from 'markdown-it'
@@ -189,11 +161,6 @@ class Ruler<Args extends unknown[], Result> {
    * Push new rule to the end of chain. See also
    * {@link Ruler.before}, {@link Ruler.after}.
    *
-   * @param ruleName Name of added rule.
-   * @param fn Rule function.
-   * @param options Rule options. `alt` is an array with names of "alternate"
-   * chains.
-   *
    * @example
    * ```javascript
    * import MarkdownIt from 'markdown-it'
@@ -221,9 +188,7 @@ class Ruler<Args extends unknown[], Result> {
    *
    * See also {@link Ruler.disable}, {@link Ruler.enableOnly}.
    *
-   * @param list List of rule names to enable.
-   * @param ignoreInvalid Set `true` to ignore errors when rule not found.
-   * @returns List of found rule names (if no exception happened).
+   * Returns list of found rule names (if no exception happened).
    */
   enable (list: string | string[], ignoreInvalid = false): string[] {
     if (!Array.isArray(list)) { list = [list] }
@@ -251,9 +216,6 @@ class Ruler<Args extends unknown[], Result> {
    * not found - throw Error. Errors can be disabled by second param.
    *
    * See also {@link Ruler.disable}, {@link Ruler.enable}.
-   *
-   * @param list List of rule names to enable (whitelist).
-   * @param ignoreInvalid Set `true` to ignore errors when rule not found.
    */
   enableOnly (list: string | string[], ignoreInvalid = false): void {
     if (!Array.isArray(list)) { list = [list] }
@@ -269,9 +231,7 @@ class Ruler<Args extends unknown[], Result> {
    *
    * See also {@link Ruler.enable}, {@link Ruler.enableOnly}.
    *
-   * @param list List of rule names to disable.
-   * @param ignoreInvalid Set `true` to ignore errors when rule not found.
-   * @returns List of found rule names (if no exception happened).
+   * Returns list of found rule names (if no exception happened).
    */
   disable (list: string | string[], ignoreInvalid = false): string[] {
     if (!Array.isArray(list)) { list = [list] }

src/types.ts

@@ -47,19 +47,39 @@ export interface Delimiter {
  * @category Main
  */
 export interface MarkdownItOptions {
-  /** Enable HTML tags in source. */
+  /**
+   * Enable HTML tags in source.
+   *
+   * @defaultValue `false` (`true` for `'commonmark'` preset only)
+   */
   html?: boolean
 
-  /** Use '/' to close single tags (`<br />`). */
+  /**
+   * Use '/' to close single tags (`<br />`).
+   *
+   * @defaultValue `false` (`true` for `'commonmark'` preset only)
+   */
   xhtmlOut?: boolean
 
-  /** Convert '\n' in paragraphs into `<br>`. */
+  /**
+   * Convert '\n' in paragraphs into `<br>`.
+   *
+   * @defaultValue `false`
+   */
   breaks?: boolean
 
-  /** CSS language prefix for fenced blocks, used by external syntax highlighters. */
+  /**
+   * CSS language prefix for fenced blocks, used by external syntax highlighters.
+   *
+   * @defaultValue `'language-'`
+   */
   langPrefix?: string
 
-  /** Autoconvert URL-like text to links. */
+  /**
+   * Autoconvert URL-like text to links.
+   *
+   * @defaultValue `false`
+   */
   linkify?: boolean
 
   /**
@@ -67,6 +87,8 @@ export interface MarkdownItOptions {
    *
    * See the [replacement rules](https://github.com/markdown-it/markdown-it/blob/master/src/rules_core/replacements.ts)
    * for the full list.
+   *
+   * @defaultValue `false`
    */
   typographer?: boolean
 
@@ -76,6 +98,8 @@ export interface MarkdownItOptions {
    *
    * For example, use `'«»„“'` for Russian, `'„“‚‘'` for German, and
    * `['«\xA0', '\xA0»', '‹\xA0', '\xA0›']` for French (including nbsp).
+   *
+   * @defaultValue `'“”‘’'`
    */
   quotes?: string | string[]
 
@@ -125,9 +149,15 @@ export interface MarkdownItOptions {
    *   }
    * });
    * ```
+   *
+   * @defaultValue `null`
    */
   highlight?: ((str: string, lang: string, attrs: string) => string) | null
 
-  /** Internal protection against excessive recursion. */
+  /**
+   * Internal protection against excessive recursion.
+   *
+   * @defaultValue `100`
+   */
   maxNesting?: number
 }