@endevops/effect-codec-xml 0.0.1 → 0.1.0-beta.2

package/src/namespaces.ts

@@ -19,21 +19,21 @@
 //   - `xmlValue` marks one field as the element's character data, the `#text`
 //     value, for an element that also carries attributes or children.
 //
-// The namespace of an element is inherited by its descendants, the way an XML
-// default namespace is. An attribute never inherits: it is in a namespace only
-// when it is annotated with one explicitly, because a default namespace does
-// not apply to attributes.
+// An element's namespace is inherited by its descendants, as an XML default
+// namespace is. An attribute never inherits: it is in a namespace only when it
+// is annotated with one explicitly, because a default namespace does not apply
+// to attributes.
 //
-// On the way out, each element writes its own declaration when the prefix or
-// default is not already in scope. On the way in, the parser's own declarations
-// are read into scope and every name is resolved to its URI, so a document that
-// binds the same URI to a different prefix still decodes to the same value. The
-// declaration attributes are dropped from the decoded value; they are the
-// codec's to manage, not the schema's.
+// On encode, each element writes its own declaration when the prefix or default
+// is not already in scope. On decode, the parser's own declarations are read
+// into scope and every name is resolved to its URI, so a document that binds the
+// same URI to a different prefix still decodes to the same value. The
+// declaration attributes are dropped from the decoded value; the codec manages
+// them, not the schema.
 //
-// The plan is built per local name, which is what a schema field is. One local
-// name cannot belong to two namespaces in one codec; that is reported when the
-// codec is built rather than guessed at.
+// The plan is built per local name, and a schema field is one local name. One
+// local name cannot belong to two namespaces in one codec; the plan reports that
+// when the codec is built rather than guessing.
 
 import type { Schema } from 'effect';
 
@@ -396,7 +396,7 @@ interface Scan {
   readonly problems: Array<string>;
   /**
    * @description The AST nodes on the current scan path. A recursive schema terminates because the `Suspend` node is still on the path when its thunk is reached,
-   * and a schema reused under two sibling paths is scanned once per path because each node is removed again on the way out.
+   * and a schema reused under two sibling paths is scanned once per path because each node is removed again on the way back out.
    */
   readonly seen: Set<SchemaAST.AST>;
 }
@@ -634,7 +634,7 @@ const scanNode = (scan: Scan, ast: SchemaAST.AST, inherited: XmlNamespace | unde
 };
 
 /**
- * @description Collects the namespace and name of every field in a schema. A namespace is inherited by descendant elements, the way a default namespace is, and an
+ * @description Collects the namespace and name of every field in a schema. Descendant elements inherit a namespace, as they inherit a default namespace, and an
  * element field records its own namespace, so encode and decode can find it by the local name alone.
  *
  * @param schema - The schema to walk.
@@ -900,7 +900,7 @@ const schemaKey = (plan: NamespacePlan, parent: string, key: string, scope: Reco
 /**
  * @description The scope a child element resolves its own name against: the declarations it carries on itself, layered over the parent scope. An element may
  * declare the prefix it uses on the element itself, so its own name is read with those bindings in scope. A repeated element arrives as an array, so
- * the first member stands in for the run — every member describes the same element and carries the same declaration.
+ * the first member stands in for the run; every member describes the same element and carries the same declaration.
  *
  * @param child - The child value.
  * @param scope - The bindings in scope above the child.
@@ -915,31 +915,32 @@ const childScopeOf = (child: XmlValue, scope: Record<string, string | undefined>
 };
 
 /**
- * @description Rewrites a wire value tree back to the schema's local names, resolving every name against the declarations the document carries and dropping those
- * declarations. Character data maps to the value field of the element it belongs to. A record left holding only character data collapses back to that
- * string, which is how a namespaced leaf stays a `Schema.String`.
+ * @description Character data read back as a value tree. An element the schema reads as a struct with a value field derives that field from the element's
+ * character data, and the parser reduces an element with no attributes and no children to a bare string, so the string is put back under the value's
+ * key for that struct to read.
  *
- * @param value - The parsed wire tree.
+ * @param value - The character data the parser produced.
+ * @param plan - The namespace plan.
+ * @param elementPath - The path of the element the character data belongs to.
+ *
+ * @returns The character data, under the element's value key when it has one.
+ */
+const decodeText = (value: string, plan: NamespacePlan, elementPath: string): XmlValue => {
+  const valueKey = plan.valueByElement.get(elementPath);
+  return valueKey !== undefined ? { [valueKey]: value } : value;
+};
+
+/**
+ * @description One record read back: its declarations dropped, its keys resolved to the schema's names, and its character data placed under the value field.
+ *
+ * @param record - The record to read.
  * @param plan - The namespace plan.
  * @param scope - The prefix bindings in scope above this element.
  * @param elementPath - The path of this element, or the root sentinel.
  *
- * @returns The value tree, keyed by the schema's names.
+ * @returns The record, keyed by the schema's names, or the string it collapses to.
  */
-export const decodeNames = (value: XmlValue, plan: NamespacePlan, scope: Record<string, string | undefined>, elementPath: string): XmlValue => {
-  if (Array.isArray(value)) {
-    return value.map(member => decodeNames(member, plan, scope, elementPath));
-  }
-  if (Predicate.isString(value) || Predicate.isUndefined(value)) {
-    return value;
-  }
-  if (!Predicate.isObject(value)) {
-    return value;
-  }
-
-  // `Predicate.isObject` narrows to a generic index signature, so the value
-  // tree's own record type is named here.
-  const record = value as XmlRecord;
+const decodeRecord = (record: XmlRecord, plan: NamespacePlan, scope: Record<string, string | undefined>, elementPath: string): XmlValue => {
   const inner = scopeOf(record, scope);
   const valueKey = plan.valueByElement.get(elementPath);
   const out: Record<string, XmlValue> = {};
@@ -950,7 +951,7 @@ export const decodeNames = (value: XmlValue, plan: NamespacePlan, scope: Record<
     }
 
     if (key === TEXT_KEY) {
-      out[valueKey ?? TEXT_KEY] = decodeNames(child, plan, inner, elementPath);
+      out[valueKey ?? TEXT_KEY] = child;
       continue;
     }
 
@@ -966,3 +967,28 @@ export const decodeNames = (value: XmlValue, plan: NamespacePlan, scope: Record<
   }
   return out;
 };
+
+/**
+ * @description Rewrites a wire value tree back to the schema's local names, resolving every name against the declarations the document carries and dropping those
+ * declarations. Character data maps to the value field of the element it belongs to. A record left holding only character data collapses back to that
+ * string, which is how a namespaced leaf stays a `Schema.String`.
+ *
+ * @param value - The parsed wire tree.
+ * @param plan - The namespace plan.
+ * @param scope - The prefix bindings in scope above this element.
+ * @param elementPath - The path of this element, or the root sentinel.
+ *
+ * @returns The value tree, keyed by the schema's names.
+ */
+export const decodeNames = (value: XmlValue, plan: NamespacePlan, scope: Record<string, string | undefined>, elementPath: string): XmlValue => {
+  if (Array.isArray(value)) {
+    return value.map(member => decodeNames(member, plan, scope, elementPath));
+  }
+  if (Predicate.isString(value)) {
+    return decodeText(value, plan, elementPath);
+  }
+  if (!Predicate.isObject(value)) {
+    return value;
+  }
+  return decodeRecord(value as XmlRecord, plan, scope, elementPath);
+};

package/src/naming.ts

@@ -8,10 +8,10 @@
 //
 // The five predicates and `sanitize` are plain synchronous functions: a regex
 // test cannot fail and a character substitution has nothing to fail about, so
-// there is no effect to model. `validate` does have one failure to report — an
+// there is no effect to model. `validate` does have one failure to report: an
 // unknown production, unreachable from TypeScript where `Production` is a
 // closed union but reachable for an untyped JavaScript caller, or a value that
-// crossed a boundary as `unknown` — so it answers with an `Effect` whose error
+// crossed a boundary as `unknown`. It answers with an `Effect` whose error
 // channel is that {@link XmlError}. The value it produces is still a plain
 // result.
 
@@ -20,7 +20,7 @@ import { Effect } from 'effect';
 import { XmlError } from '#/xml-error.ts';
 
 /**
- * @description The XML specification version a production is validated against. The two differ only in their non-ASCII character ranges — see {@link getRegexes}.
+ * @description The XML specification version a production is validated against. The two differ only in their non-ASCII character ranges. See {@link getRegexes}.
  */
 export type XmlVersion = '1.0' | '1.1';
 
@@ -42,7 +42,7 @@ export interface ValidationOptions {
   /**
    * @description Restrict matching to the ASCII subset of the NameStartChar/NameChar productions and skip unicode-aware regex matching entirely. Faster,
    * especially for XML 1.1 (which otherwise requires the `/u` regex flag), but rejects legitimate non-ASCII XML names. Off by default for backward
-   * compatibility — opt in only when inputs are known to be ASCII. Defaults to false.
+   * compatibility. Opt in only when inputs are known to be ASCII. Defaults to false.
    */
   asciiOnly?: boolean;
 }
@@ -60,7 +60,7 @@ export interface SanitizeOptions {
    */
   asciiOnly?: boolean;
   /**
-   * @description Accepted and ignored. Sanitizing is not version-dependent — the character set it considers illegal is the union of both versions — but the option
+   * @description Accepted and ignored. Sanitizing is not version-dependent: the character set it considers illegal is the union of both versions. But the option
    * is part of the published signature, so dropping it would break callers that pass it through a shared options object.
    */
   xmlVersion?: XmlVersion;
@@ -94,7 +94,7 @@ const PRODUCTIONS = ['name', 'ncName', 'qName', 'nmToken', 'nmTokens'] as const
 type ProductionRegexes = Record<Production, RegExp>;
 
 // ---------------------------------------------------------------------------
-// Character class strings — XML 1.0
+// Character class strings: XML 1.0
 //
 // NameStartChar ::= ":" | [A-Z] | "_" | [a-z]
 //   | [#xC0-#xD6]   | [#xD8-#xF6]   | [#xF8-#x2FF]
@@ -127,7 +127,7 @@ const nameStartChar10 =
 const nameChar10 = nameStartChar10 + '\\-\\.\\d' + '\u00B7' + '\u0300-\u036F' + '\u203F-\u2040';
 
 // ---------------------------------------------------------------------------
-// Character class strings — XML 1.1
+// Character class strings: XML 1.1
 //
 // Differences from XML 1.0:
 //
@@ -138,7 +138,7 @@ const nameChar10 = nameStartChar10 + '\\-\\.\\d' + '\u00B7' + '\u0300-\u036F' +
 //
 //   1.0 tops out at \uFFFD (BMP only)
 //   1.1 adds \u{10000}-\u{EFFFF} (supplementary planes)
-//   These require the /u flag on the RegExp — see buildRegexes below.
+//   These require the /u flag on the RegExp. See buildRegexes below.
 //
 // NameChar:
 //   1.1 adds \u0487 (Combining Cyrillic Millions Sign, added in Unicode 4.0)
@@ -146,7 +146,7 @@ const nameChar10 = nameStartChar10 + '\\-\\.\\d' + '\u00B7' + '\u0300-\u036F' +
 
 const nameStartChar11 =
   ':A-Za-z_' +
-  '\u00C0-\u02FF' + // merged — 1.0 had three split ranges here
+  '\u00C0-\u02FF' + // merged: 1.0 had three split ranges here
   '\u0370-\u037D' +
   '\u037F-\u0486\u0488-\u1FFF' + // split to exclude \u0487 (combining mark, never a NameStartChar)
   '\u200C-\u200D' +
@@ -155,21 +155,21 @@ const nameStartChar11 =
   '\u3001-\uD7FF' +
   '\uF900-\uFDCF' +
   '\uFDF0-\uFFFD' +
-  '\u{10000}-\u{EFFFF}'; // supplementary planes — REQUIRES /u flag on RegExp
+  '\u{10000}-\u{EFFFF}'; // supplementary planes: REQUIRES /u flag on RegExp
 
 const nameChar11 =
   nameStartChar11 +
   '\\-\\.\\d' +
   '\u00B7' +
   '\u0300-\u036F' +
-  '\u0487' + // Combining Cyrillic Millions Sign — valid in 1.1, not 1.0
+  '\u0487' + // Combining Cyrillic Millions Sign: valid in 1.1, not 1.0
   '\u203F-\u2040';
 
 // ---------------------------------------------------------------------------
 // Regex builders
 //
-// XML 1.0 regexes: no flags — BMP only, standard JS regex behaviour.
-// XML 1.1 regexes: /u flag — required for \u{10000}-\u{EFFFF} to match actual
+// XML 1.0 regexes: no flags, BMP only, standard JS regex behaviour.
+// XML 1.1 regexes: /u flag, required for \u{10000}-\u{EFFFF} to match actual
 //   supplementary code points rather than lone surrogates (which are illegal XML).
 // ---------------------------------------------------------------------------
 
@@ -196,34 +196,33 @@ const buildRegexes = (startChar: string, char: string, flags = ''): ProductionRe
   };
 };
 
-const regexes10 = buildRegexes(nameStartChar10, nameChar10); // no /u — BMP only
-const regexes11 = buildRegexes(nameStartChar11, nameChar11, 'u'); // /u — enables \u{10000}-\u{EFFFF}
+const regexes10 = buildRegexes(nameStartChar10, nameChar10); // no /u, BMP only
+const regexes11 = buildRegexes(nameStartChar11, nameChar11, 'u'); // /u enables \u{10000}-\u{EFFFF}
 
 // ---------------------------------------------------------------------------
 // ASCII-only fast path (opt-in, off by default)
 //
-// The XML 1.0 vs 1.1 NameStartChar/NameChar productions differ *only* in
-// their non-ASCII ranges (merged vs split Latin-1 ranges, \u0487, and
-// supplementary planes). Restricted to ASCII, both versions collapse to the
-// same character classes, so a single regex pair covers both xmlVersion
-// values — no /u flag needed.
+// The XML 1.0 and 1.1 NameStartChar/NameChar productions differ only in their
+// non-ASCII ranges: merged vs split Latin-1 ranges, \u0487, and supplementary
+// planes. Restricted to ASCII, both versions collapse to the same character
+// classes, so one regex pair covers both xmlVersion values and no /u flag is
+// needed.
 //
-// Rationale: unicode-aware regexes (the /u flag, required for XML 1.1's
-// supplementary-plane range) are measurably slower in V8 than plain
-// non-unicode regexes on the same input, even when the input is pure ASCII.
-// For the common case — HTML/SVG ids, XML tags — names are ASCII, so callers
-// who know this can opt in to skip the unicode-aware matching path entirely.
-// This is a real but *conditional* win: mainly for XML 1.1 input (avoids /u),
-// or at scale where the larger unicode character classes add engine
-// overhead. It also changes behaviour (rejects legitimate non-ASCII XML
-// 1.0/1.1 names), so it must never be silently enabled — hence off by
-// default.
+// Unicode-aware regexes (the /u flag, required for XML 1.1's supplementary-
+// plane range) are measurably slower in V8 than plain non-unicode regexes on
+// the same input, even when the input is pure ASCII. For the common case
+// (HTML/SVG ids, XML tags) names are ASCII, so callers who know this can opt
+// in to skip the unicode-aware matching path entirely. The win is conditional:
+// it applies mainly to XML 1.1 input (avoids /u), or at scale where the larger
+// unicode character classes add engine overhead. The option also changes
+// behaviour (it rejects legitimate non-ASCII XML 1.0/1.1 names), so it must
+// never be enabled silently. That is why the default is off.
 // ---------------------------------------------------------------------------
 
 const nameStartCharAscii = ':A-Za-z_';
 const nameCharAscii = nameStartCharAscii + '\\-\\.\\d';
 
-const regexesAscii = buildRegexes(nameStartCharAscii, nameCharAscii); // no /u — ASCII only
+const regexesAscii = buildRegexes(nameStartCharAscii, nameCharAscii); // no /u, ASCII only
 
 /**
  * @description The compiled regex set for a version/ASCII combination. Only three sets are ever built, at module load; this is a lookup, not a compile.
@@ -242,7 +241,7 @@ const getRegexes = (xmlVersion: XmlVersion = '1.0', asciiOnly = false): Producti
 // Boolean validators
 //
 // One plain predicate per production. A regex test cannot fail, and every one of these is called per name
-// inside a parser's or codec's hot loop, so a boolean is the honest answer and there is no effect to
+// inside a parser's or codec's hot loop, so a boolean is the direct answer and there is no effect to
 // allocate or run.
 // ---------------------------------------------------------------------------
 
@@ -296,7 +295,7 @@ export const isNmToken = (str: string, { xmlVersion = '1.0', asciiOnly = false }
   getRegexes(xmlVersion, asciiOnly).nmToken.test(str);
 
 /**
- * @description Whether the string is a valid NMTokens value — a whitespace-separated list of NMToken values. Used for: DTD NMTOKENS attribute values.
+ * @description Whether the string is a valid NMTokens value: a whitespace-separated list of NMToken values. Used for: DTD NMTOKENS attribute values.
  *
  * @param str - The candidate list.
  * @param opts - `asciiOnly` skips unicode-aware matching, ASCII names only (default false).
@@ -455,7 +454,7 @@ const diagnoseWith = (str: string, production: Production, isValid: boolean, asc
  * @example
  *   ```typescript
  *   import { Effect } from 'effect';
- *   import { validate } from '@endevops/effect-xml-codec';
+ *   import { validate } from '@endevops/effect-codec-xml';
  *
  *   Effect.runSync(validate('not a name', 'ncName'));
  *   // { valid: false, production: 'ncName', input: 'not a name', reason: 'First character " " is not a valid NameStartChar', position: 0 }
@@ -466,7 +465,7 @@ const diagnoseWith = (str: string, production: Production, isValid: boolean, asc
  * @param opts - Version and ASCII-only selection, as for the boolean validators.
  *
  * @returns An effect producing a discriminated result: the plain triple when valid, or the offending `reason` and `position` when not. A name that
- *   fails to validate is a `valid: false` result, not a failure — an invalid name is the question being answered. The effect fails only with an
+ *   fails to validate is a `valid: false` result, not a failure: an invalid name is the question being answered. The effect fails only with an
  *   {@link XmlError} and the `InvalidProduction` reason for an unknown production, which is unreachable from TypeScript and is the guard for untyped
  *   JavaScript callers.
  */

package/src/parse.ts

@@ -34,7 +34,7 @@ export interface XmlParseOptions {
    * @description Keep the whitespace at the edges of every text run.
    *
    * @default false\
-   * which trims it — and trimming is what makes a pretty-printed document
+   * which trims it. Trimming makes a pretty-printed document
    * read as the same value as an unindented one, because the indentation around a child element and around a closing tag lands at the edges of its
    * parent's text. Whitespace _inside_ a run is content and is never touched either way, so `'one two'` and a paragraph with a newline in the middle
    * of it survive. Set it to `true` to keep leading and trailing spaces in text exactly as written, at the cost of a document that was laid out on
@@ -68,13 +68,13 @@ export interface XmlParseOptions {
 /**
  * @description Parses an XML document into its root element's content.\
  * The walk itself is synchronous, but it reports a malformed document by failing with an {@link XmlParseError} rather than by throwing, so the failure lands in the effect's error channel where `catchTag`, `retry` and a fallback can all
- * see it. A failed parse is an expected outcome of reading untrusted text — it is what those combinators key off — and only a defect would hide it.
+ * see it. A failed parse is an expected outcome of reading untrusted text, and those combinators key off it, so only a defect would hide it.
  * The span is the boundary a performance trace hangs off: it carries the document's length, which is the size that drives the parser's cost, so a
  * slow parse in a profile can be attributed to the input that produced it. A caller that wants the value outside an `Effect` uses
  * {@link parseXmlDocument}, which runs the same walk synchronously and throws instead. The walk is plain recursive descent rather than a chain of
- * `yield*`es. Publicly `parseXml` is still an `Effect` — it suspends the walk so it runs lazily under the span, and folds the failure the walk throws
- * into the typed error channel — but inside a document there is no effect boundary per tag, attribute or text run. A 500-row report is thousands of
- * those, and a fiber step for each of them was most of what the `parse 500 rows` row measured. The typed failure survives: the walk throws an
+ * `yield*`es. Publicly `parseXml` is still an `Effect`: it suspends the walk so it runs lazily under the span, and folds the failure the walk throws
+ * into the typed error channel, but inside a document there is no effect boundary per tag, attribute or text run. A 500-row report is thousands of
+ * those, and one fiber step per construct dominated the `parse 500 rows` benchmark. The typed failure survives: the walk throws an
  * {@link XmlParseError} and `parseXml` catches it into `Effect.fail`.
  *
  * @param text - The document to read.
@@ -140,8 +140,8 @@ const SLASH = 47;
 const EQUALS = 61;
 
 /**
- * @description One element as the parser saw it: the name it was written under, and the value it holds. Carrying the name alongside the value is what lets the
- * parent file it correctly — the value alone cannot say, because a text-only element reduces to a bare string.
+ * @description One element as the parser saw it: the name it was written under, and the value it holds. Carrying the name alongside the value lets the parent file
+ * it correctly, because the value alone cannot say: a text-only element reduces to a bare string.
  */
 interface Element {
   readonly name: string;
@@ -179,9 +179,9 @@ interface Content {
 }
 
 /**
- * @description What sits at the cursor inside an element's body. Naming what is there before deciding what to do with it is what lets the content loop stay a
- * dispatch: each construct is recognised in one place, against the ones that cannot be confused with it, rather than by a chain of `startsWith`
- * guesses where each had to remember what the last had already ruled out.
+ * @description What sits at the cursor inside an element's body. Naming what is there before deciding what to do with it lets the content loop stay a dispatch:
+ * each construct is recognised in one place, against the ones that cannot be confused with it, rather than by a chain of `startsWith` guesses where
+ * each had to remember what the last had already ruled out.
  */
 type Construct = 'text' | 'close' | 'comment' | 'cdata' | 'instruction' | 'child';
 
@@ -213,7 +213,7 @@ const parseDocument = (text: string, options: XmlParseOptions): XmlDocument => {
   const nameOptions = { mode: resolved.name, xmlVersion: resolved.xmlVersion };
 
   /**
-   * @description Names already resolved by this parse. A document repeats names — every one of five hundred rows has a `sku` — and a validator that ran per
+   * @description Names already resolved by this parse. A document repeats names (every one of five hundred rows has a `sku`), and a validator that ran per
    * occurrence would pay for the same answer five hundred times.
    */
   const nameCache = new Map<string, string>();
@@ -258,7 +258,7 @@ const parseDocument = (text: string, options: XmlParseOptions): XmlDocument => {
   };
 
   /**
-   * @description Consumes whitespace, comments, processing instructions and a DOCTYPE, leaving the cursor on the first character that is none of them — or at the
+   * @description Consumes whitespace, comments, processing instructions and a DOCTYPE, leaving the cursor on the first character that is none of them, or at the
    * end of the document.
    */
   const skipMisc = (): void => {
@@ -294,7 +294,7 @@ const parseDocument = (text: string, options: XmlParseOptions): XmlDocument => {
     const start = at;
     while (at < text.length) {
       const char = text.charCodeAt(at);
-      // Whitespace, `/`, `=` and `>` all end a name. Stopping on `/` and `>` is what lets `<a/>` and `<a>` share one loop.
+      // Whitespace, `/`, `=` and `>` all end a name. Stopping on `/` and `>` lets `<a/>` and `<a>` share one loop.
       if (isWhitespace(char) || char === SLASH || char === EQUALS || char === GT) {
         break;
       }
@@ -322,7 +322,7 @@ const parseDocument = (text: string, options: XmlParseOptions): XmlDocument => {
     at++;
 
     const end = text.indexOf(quote ?? '', at);
-    // A raw quote cannot appear inside a quoted value — it would have to be written `&quot;` — so the next quote of the same kind always closes it.
+    // A raw quote cannot appear inside a quoted value (it would have to be written `&quot;`), so the next quote of the same kind always closes it.
     if (end === -1) {
       throw new XmlParseError({ message: `Unterminated value for attribute "${name}"`, position: at, input: text });
     }
@@ -425,8 +425,8 @@ const parseDocument = (text: string, options: XmlParseOptions): XmlDocument => {
   /**
    * @description What the cursor is sitting on inside an element's body. The two things the loop cannot read are refused here rather than in it: running out of
    * document and a declaration, which is markup the parser does not accept inside an element. Recognising the constructs that _are_ read is the rest,
-   * and the order is the one that rules out the shorter prefixes first — `</` before `<?` before any other `<!`, and `<![CDATA[` before the `<!` that
-   * would otherwise match it.
+   * and the order rules out the shorter prefixes first: `</` before `<?` before any other `<!`, and `<![CDATA[` before the `<!` that would otherwise
+   * match it.
    *
    * @param name - The name the enclosing element's start tag gave it, for the unterminated-body message.
    *
@@ -458,7 +458,7 @@ const parseDocument = (text: string, options: XmlParseOptions): XmlDocument => {
   };
 
   /**
-   * @description Consumes a `</name>`, checking on the way that it is the tag that closes this element and that it is well-formed.
+   * @description Consumes a `</name>`, checking as it goes that it is the tag that closes this element and that it is well-formed.
    *
    * @param name - The name the start tag gave the element, which the closing tag has to match.
    */
@@ -490,7 +490,7 @@ const parseDocument = (text: string, options: XmlParseOptions): XmlDocument => {
   };
 
   /**
-   * @description Reads a `<![CDATA[…]]>` section. CDATA is character data, and character data is what it holds, so it joins the element's text as it stands — the
+   * @description Reads a `<![CDATA[…]]>` section. CDATA is character data, and character data is what it holds, so it joins the element's text as it stands. The
    * entities in it are literal text and must not be expanded.
    *
    * @returns The section's contents.
@@ -522,15 +522,15 @@ const parseDocument = (text: string, options: XmlParseOptions): XmlDocument => {
    */
   const finishElement = (record: Record<string, XmlValue>, hasAttributes: boolean, text: string, hasChildren: boolean): XmlValue => {
     // Whitespace at the edges of a text run is dropped unless the caller asked to
-    // keep it. This is what makes a pretty-printed document round trip: the
+    // keep it. Trimming here makes a pretty-printed document round trip: the
     // indentation a renderer puts around a child element and around a closing tag
     // lands at the edges of its parent's text, and trimming removes exactly that
-    // and nothing else. Whitespace *inside* the run — between two words, or a
-    // newline in the middle of a paragraph — is content and stays.
+    // and nothing else. Whitespace *inside* the run (between two words, or a
+    // newline in the middle of a paragraph) is content and stays.
     const content = resolved.preserveWhitespace ? text : text.trim();
 
     if (!hasAttributes && !hasChildren) {
-      // A leaf is character data on its own. Returning the string rather than a `{ '#text': … }` record is what lets
+      // A leaf is character data on its own. Returning the string rather than a `{ '#text': … }` record lets
       // `Schema.Struct({ name: Schema.String })` round-trip.
       return content;
     }
@@ -577,10 +577,10 @@ const parseDocumentResult = (text: string, options: XmlParseOptions): Result.Res
 };
 
 /**
- * @description Decodes character references, falling back to the raw text when the reference is not one the decoder recognises. The fallback is what makes a bare
- * `&` survivable: the decoder treats it as a malformed reference and fails, and a document containing one is far more likely to be worth reading than
- * to be rejected. The `&` is escaped on the way out, so the value still round-trips. The decoder answers with an `Effect`, and this is the one place
- * a parse still runs one. It is only reached when the raw text holds an `&` — the common case returns before it — and the effect is synchronous, so
+ * @description Decodes character references, falling back to the raw text when the reference is not one the decoder recognises. The fallback keeps a bare `&`
+ * survivable: the decoder treats it as a malformed reference and fails, and a document containing one is far more likely to be worth reading than to
+ * be rejected. The `&` is escaped on the way out, so the value still round-trips. The decoder answers with an `Effect`, and this is the one place a
+ * parse still runs one. It is only reached when the raw text holds an `&`, since the common case returns before it, and the effect is synchronous, so
  * the run is cheap next to the decoder's own work.
  *
  * @param raw - Text read straight from the source, with references unexpanded.