docs(markdown): document markdown utility functions

Add @PARAM, @returns and runnable examples to the public markdown
utility JSDoc.

Author: bdbch

packages/markdown/src/utils/assumeContentType.ts

@@ -7,6 +7,10 @@ import type { ContentType } from '../types.js'
  * Assume the content type based on the content value.
  * @param content The content to assume the type for.
  * @param contentType The content type that should be prioritized.
+ * @returns 'json' when the content is not a string, otherwise the given contentType.
+ * @example
+ * assumeContentType({ type: 'paragraph' }, 'html') // => 'json'
+ * assumeContentType('**bold**', 'markdown') // => 'markdown'
  */
 export function assumeContentType(
   content: (Content | Fragment | Node) | string,

packages/markdown/src/utils/closeMarksBeforeNode.ts

@@ -3,6 +3,13 @@ import type { JSONMark } from '../types.js'
 /**
  * Closes active marks before rendering a non-text node.
  * Returns the closing markdown syntax and clears the active marks.
+ * @param activeMarks The marks to close.
+ * @param getMarkClosing Returns the closing syntax for a mark.
+ * @returns The concatenated closing syntax, innermost mark last.
+ * @example
+ * const active = new Map([['bold', { type: 'bold' }], ['italic', { type: 'italic' }]])
+ * closeMarksBeforeNode(active, markType => (markType === 'bold' ? '**' : '*'))
+ * // => '***'  (italic closes before bold, LIFO)
  */
 export function closeMarksBeforeNode(
   activeMarks: Map<string, JSONMark>,

packages/markdown/src/utils/extractAbsorbedBlankLines.ts

@@ -12,6 +12,9 @@ const TRAILING_BLANK_LINES = /\n[^\S\n]*(?:\n[^\S\n]*)+$/
  * Recover blank lines absorbed into token `raw` as explicit `space` tokens.
  * @param tokens The marked token stream to normalize.
  * @returns A new token array with absorbed blank lines as `space` tokens.
+ * @example
+ * extractAbsorbedBlankLines([{ type: 'paragraph', raw: 'hello\n\n' }])
+ * // => [{ type: 'paragraph', raw: 'hello' }, { type: 'space', raw: '\n\n' }]
  */
 export function extractAbsorbedBlankLines(tokens: MarkdownToken[]): MarkdownToken[] {
   return tokens.flatMap((token, index) =>

packages/markdown/src/utils/findMarksToClose.ts

@@ -6,6 +6,18 @@ import type { JSONMark } from '../types.js'
 /**
  * Determines which marks to close based on the next node's marks,
  * treating same-type marks with different attributes as distinct.
+ * @param currentMarks The marks on the current text node.
+ * @param nextNode The following node, or null when this is the last node.
+ * @returns The mark types that do not continue on the next node.
+ * @example
+ * findMarksToClose(new Map([['bold', { type: 'bold' }]]), null)
+ * // => ['bold']
+ * findMarksToClose(new Map([['bold', { type: 'bold' }]]), {
+ *   type: 'text',
+ *   text: 'x',
+ *   marks: [{ type: 'bold' }],
+ * })
+ * // => []  (bold continues on the next node)
  */
 export function findMarksToClose(
   currentMarks: Map<string, JSONMark>,

packages/markdown/src/utils/findMarksToCloseAtEnd.ts

@@ -6,6 +6,15 @@ import type { JSONMark } from '../types.js'
 /**
  * Determines which marks to close at the node end, treating same-type marks
  * with different attributes as distinct (close + reopen).
+ * @param activeMarks The marks currently open before this node.
+ * @param currentMarks The marks on the current text node.
+ * @param nextNode The following node, or null when this is the last node.
+ * @param markSetsEqual Callback comparing two mark sets for equality.
+ * @returns The mark types to close at the end of the current node.
+ * @example
+ * const active = new Map([['bold', { type: 'bold' }], ['italic', { type: 'italic' }]])
+ * findMarksToCloseAtEnd(active, active, null, () => false)
+ * // => ['italic', 'bold']  (all active marks close, LIFO)
  */
 export function findMarksToCloseAtEnd(
   activeMarks: Map<string, JSONMark>,

packages/markdown/src/utils/findMarksToOpen.ts

@@ -5,6 +5,13 @@ import type { JSONMark } from '../types.js'
 /**
  * Determines which marks need to open, treating same-type marks with
  * different attributes as distinct (close + reopen).
+ * @param activeMarks The marks already open.
+ * @param currentMarks The marks on the current text node.
+ * @returns The marks that are not yet active, or whose attributes differ.
+ * @example
+ * const active = new Map([['bold', { type: 'bold' }]])
+ * findMarksToOpen(active, new Map([['bold', { type: 'bold' }], ['italic', { type: 'italic' }]]))
+ * // => [{ type: 'italic', mark: { type: 'italic' } }]
  */
 export function findMarksToOpen(
   activeMarks: Map<string, JSONMark>,

packages/markdown/src/utils/reopenMarksAfterNode.ts

@@ -3,6 +3,18 @@ import type { JSONMark } from '../types.js'
 /**
  * Reopens marks after rendering a non-text node.
  * Returns the opening markdown syntax and updates the active marks.
+ * @param marksToReopen The marks to reopen on the following text.
+ * @param activeMarks The marks to restore.
+ * @param getMarkOpening Returns the opening syntax for a mark.
+ * @returns The concatenated opening syntax.
+ * @example
+ * const active = new Map()
+ * reopenMarksAfterNode(
+ *   new Map([['bold', { type: 'bold' }], ['italic', { type: 'italic' }]]),
+ *   active,
+ *   () => '*',
+ * )
+ * // => '**'
  */
 export function reopenMarksAfterNode(
   marksToReopen: Map<string, JSONMark>,

packages/markdown/src/utils/wrapInMarkdownBlock.ts

@@ -3,6 +3,8 @@
  * @param prefix The prefix to wrap each line with.
  * @param content The content to wrap.
  * @returns The content with each line wrapped with the prefix.
+ * @example
+ * wrapInMarkdownBlock('> ', 'first\nsecond') // => '> first\n> \n> second'
  */
 export function wrapInMarkdownBlock(prefix: string, content: string) {
   // split content lines