Add improved docs

Author: wooorm

index.js

@@ -2,16 +2,19 @@
  * @typedef {import('./lib/types.js').Info} SafeOptions
  *   To do: remove next major: renamed because it doesn’t really reflect
  *   options, but instead info on the surrounding of the generated thing.
+ * @typedef {import('./lib/types.js').State} Context
+ *   To do: remove next major: renamed because the word state more clearly
+ *   represents one thing that is passed down to everything and is changed.
  */
 
 /**
- * @typedef {import('./lib/types.js').Info} Info
- * @typedef {import('./lib/types.js').Context} Context
  * @typedef {import('./lib/types.js').Handle} Handle
  * @typedef {import('./lib/types.js').Handlers} Handlers
+ * @typedef {import('./lib/types.js').Info} Info
  * @typedef {import('./lib/types.js').Join} Join
- * @typedef {import('./lib/types.js').Unsafe} Unsafe
  * @typedef {import('./lib/types.js').Options} Options
+ * @typedef {import('./lib/types.js').State} State
+ * @typedef {import('./lib/types.js').Unsafe} Unsafe
  * @typedef {import('./lib/util/indent-lines.js').Map} Map
  */
 

lib/configure.js

@@ -1,12 +1,12 @@
 /**
  * @typedef {import('./types.js').Options} Options
- * @typedef {import('./types.js').Context} Context
+ * @typedef {import('./types.js').State} State
  */
 
 /**
- * @param {Context} base
+ * @param {State} base
  * @param {Options} extension
- * @returns {Context}
+ * @returns {State}
  */
 export function configure(base, extension) {
   let index = -1

lib/handle/blockquote.js

@@ -1,7 +1,7 @@
 /**
  * @typedef {import('mdast').Blockquote} Blockquote
  * @typedef {import('../types.js').Parent} Parent
- * @typedef {import('../types.js').Context} Context
+ * @typedef {import('../types.js').State} State
  * @typedef {import('../types.js').Info} Info
  * @typedef {import('../util/indent-lines.js').Map} Map
  */
@@ -13,19 +13,16 @@ import {track} from '../util/track.js'
 /**
  * @param {Blockquote} node
  * @param {Parent | undefined} _
- * @param {Context} context
+ * @param {State} state
  * @param {Info} info
  * @returns {string}
  */
-export function blockquote(node, _, context, info) {
-  const exit = context.enter('blockquote')
+export function blockquote(node, _, state, info) {
+  const exit = state.enter('blockquote')
   const tracker = track(info)
   tracker.move('> ')
   tracker.shift(2)
-  const value = indentLines(
-    containerFlow(node, context, tracker.current()),
-    map
-  )
+  const value = indentLines(containerFlow(node, state, tracker.current()), map)
   exit()
   return value
 }

lib/handle/break.js

@@ -1,7 +1,7 @@
 /**
  * @typedef {import('mdast').Break} Break
  * @typedef {import('../types.js').Parent} Parent
- * @typedef {import('../types.js').Context} Context
+ * @typedef {import('../types.js').State} State
  * @typedef {import('../types.js').Info} Info
  */
 
@@ -10,19 +10,19 @@ import {patternInScope} from '../util/pattern-in-scope.js'
 /**
  * @param {Break} _
  * @param {Parent | undefined} _1
- * @param {Context} context
+ * @param {State} state
  * @param {Info} info
  * @returns {string}
  */
-export function hardBreak(_, _1, context, info) {
+export function hardBreak(_, _1, state, info) {
   let index = -1
 
-  while (++index < context.unsafe.length) {
+  while (++index < state.unsafe.length) {
     // If we can’t put eols in this construct (setext headings, tables), use a
     // space instead.
     if (
-      context.unsafe[index].character === '\n' &&
-      patternInScope(context.stack, context.unsafe[index])
+      state.unsafe[index].character === '\n' &&
+      patternInScope(state.stack, state.unsafe[index])
     ) {
       return /[ \t]/.test(info.before) ? '' : ' '
     }

lib/handle/code.js

@@ -1,7 +1,7 @@
 /**
  * @typedef {import('mdast').Code} Code
  * @typedef {import('../types.js').Parent} Parent
- * @typedef {import('../types.js').Context} Context
+ * @typedef {import('../types.js').State} State
  * @typedef {import('../types.js').Info} Info
  * @typedef {import('../util/indent-lines.js').Map} Map
  */
@@ -16,31 +16,31 @@ import {track} from '../util/track.js'
 /**
  * @param {Code} node
  * @param {Parent | undefined} _
- * @param {Context} context
+ * @param {State} state
  * @param {Info} info
  * @returns {string}
  */
-export function code(node, _, context, info) {
-  const marker = checkFence(context)
+export function code(node, _, state, info) {
+  const marker = checkFence(state)
   const raw = node.value || ''
   const suffix = marker === '`' ? 'GraveAccent' : 'Tilde'
 
-  if (formatCodeAsIndented(node, context)) {
-    const exit = context.enter('codeIndented')
+  if (formatCodeAsIndented(node, state)) {
+    const exit = state.enter('codeIndented')
     const value = indentLines(raw, map)
     exit()
     return value
   }
 
   const tracker = track(info)
   const sequence = marker.repeat(Math.max(longestStreak(raw, marker) + 1, 3))
-  const exit = context.enter('codeFenced')
+  const exit = state.enter('codeFenced')
   let value = tracker.move(sequence)
 
   if (node.lang) {
-    const subexit = context.enter('codeFencedLang' + suffix)
+    const subexit = state.enter('codeFencedLang' + suffix)
     value += tracker.move(
-      safe(context, node.lang, {
+      safe(state, node.lang, {
         before: value,
         after: ' ',
         encode: ['`'],
@@ -51,10 +51,10 @@ export function code(node, _, context, info) {
   }
 
   if (node.lang && node.meta) {
-    const subexit = context.enter('codeFencedMeta' + suffix)
+    const subexit = state.enter('codeFencedMeta' + suffix)
     value += tracker.move(' ')
     value += tracker.move(
-      safe(context, node.meta, {
+      safe(state, node.meta, {
         before: value,
         after: '\n',
         encode: ['`'],

lib/handle/definition.js

@@ -1,7 +1,7 @@
 /**
  * @typedef {import('mdast').Definition} Definition
  * @typedef {import('../types.js').Parent} Parent
- * @typedef {import('../types.js').Context} Context
+ * @typedef {import('../types.js').State} State
  * @typedef {import('../types.js').Info} Info
  */
 
@@ -13,19 +13,19 @@ import {track} from '../util/track.js'
 /**
  * @param {Definition} node
  * @param {Parent | undefined} _
- * @param {Context} context
+ * @param {State} state
  * @param {Info} info
  * @returns {string}
  */
-export function definition(node, _, context, info) {
-  const quote = checkQuote(context)
+export function definition(node, _, state, info) {
+  const quote = checkQuote(state)
   const suffix = quote === '"' ? 'Quote' : 'Apostrophe'
-  const exit = context.enter('definition')
-  let subexit = context.enter('label')
+  const exit = state.enter('definition')
+  let subexit = state.enter('label')
   const tracker = track(info)
   let value = tracker.move('[')
   value += tracker.move(
-    safe(context, association(node), {
+    safe(state, association(node), {
       before: value,
       after: ']',
       ...tracker.current()
@@ -41,17 +41,17 @@ export function definition(node, _, context, info) {
     // If there are control characters or whitespace.
     /[\0- \u007F]/.test(node.url)
   ) {
-    subexit = context.enter('destinationLiteral')
+    subexit = state.enter('destinationLiteral')
     value += tracker.move('<')
     value += tracker.move(
-      safe(context, node.url, {before: value, after: '>', ...tracker.current()})
+      safe(state, node.url, {before: value, after: '>', ...tracker.current()})
     )
     value += tracker.move('>')
   } else {
     // No whitespace, raw is prettier.
-    subexit = context.enter('destinationRaw')
+    subexit = state.enter('destinationRaw')
     value += tracker.move(
-      safe(context, node.url, {
+      safe(state, node.url, {
         before: value,
         after: node.title ? ' ' : '\n',
         ...tracker.current()
@@ -62,10 +62,10 @@ export function definition(node, _, context, info) {
   subexit()
 
   if (node.title) {
-    subexit = context.enter('title' + suffix)
+    subexit = state.enter('title' + suffix)
     value += tracker.move(' ' + quote)
     value += tracker.move(
-      safe(context, node.title, {
+      safe(state, node.title, {
         before: value,
         after: quote,
         ...tracker.current()

lib/handle/emphasis.js

@@ -1,7 +1,7 @@
 /**
  * @typedef {import('mdast').Emphasis} Emphasis
  * @typedef {import('../types.js').Parent} Parent
- * @typedef {import('../types.js').Context} Context
+ * @typedef {import('../types.js').State} State
  * @typedef {import('../types.js').Info} Info
  */
 
@@ -18,17 +18,17 @@ emphasis.peek = emphasisPeek
 /**
  * @param {Emphasis} node
  * @param {Parent | undefined} _
- * @param {Context} context
+ * @param {State} state
  * @param {Info} info
  * @returns {string}
  */
-export function emphasis(node, _, context, info) {
-  const marker = checkEmphasis(context)
-  const exit = context.enter('emphasis')
+export function emphasis(node, _, state, info) {
+  const marker = checkEmphasis(state)
+  const exit = state.enter('emphasis')
   const tracker = track(info)
   let value = tracker.move(marker)
   value += tracker.move(
-    containerPhrasing(node, context, {
+    containerPhrasing(node, state, {
       before: value,
       after: marker,
       ...tracker.current()
@@ -42,9 +42,9 @@ export function emphasis(node, _, context, info) {
 /**
  * @param {Emphasis} _
  * @param {Parent | undefined} _1
- * @param {Context} context
+ * @param {State} state
  * @returns {string}
  */
-function emphasisPeek(_, _1, context) {
-  return context.options.emphasis || '*'
+function emphasisPeek(_, _1, state) {
+  return state.options.emphasis || '*'
 }

lib/handle/heading.js

@@ -1,7 +1,7 @@
 /**
  * @typedef {import('mdast').Heading} Heading
  * @typedef {import('../types.js').Parent} Parent
- * @typedef {import('../types.js').Context} Context
+ * @typedef {import('../types.js').State} State
  * @typedef {import('../types.js').Info} Info
  */
 
@@ -12,18 +12,18 @@ import {track} from '../util/track.js'
 /**
  * @param {Heading} node
  * @param {Parent | undefined} _
- * @param {Context} context
+ * @param {State} state
  * @param {Info} info
  * @returns {string}
  */
-export function heading(node, _, context, info) {
+export function heading(node, _, state, info) {
   const rank = Math.max(Math.min(6, node.depth || 1), 1)
   const tracker = track(info)
 
-  if (formatHeadingAsSetext(node, context)) {
-    const exit = context.enter('headingSetext')
-    const subexit = context.enter('phrasing')
-    const value = containerPhrasing(node, context, {
+  if (formatHeadingAsSetext(node, state)) {
+    const exit = state.enter('headingSetext')
+    const subexit = state.enter('phrasing')
+    const value = containerPhrasing(node, state, {
       ...tracker.current(),
       before: '\n',
       after: '\n'
@@ -45,16 +45,16 @@ export function heading(node, _, context, info) {
   }
 
   const sequence = '#'.repeat(rank)
-  const exit = context.enter('headingAtx')
-  const subexit = context.enter('phrasing')
+  const exit = state.enter('headingAtx')
+  const subexit = state.enter('phrasing')
 
   // Note: for proper tracking, we should reset the output positions when there
   // is no content returned, because then the space is not output.
   // Practically, in that case, there is no content, so it doesn’t matter that
   // we’ve tracked one too many characters.
   tracker.move(sequence + ' ')
 
-  let value = containerPhrasing(node, context, {
+  let value = containerPhrasing(node, state, {
     before: '# ',
     after: '\n',
     ...tracker.current()
@@ -71,7 +71,7 @@ export function heading(node, _, context, info) {
 
   value = value ? sequence + ' ' + value : sequence
 
-  if (context.options.closeAtx) {
+  if (state.options.closeAtx) {
     value += ' ' + sequence
   }