docs: Improve TSDocs

src/FeedHandler.ts

@@ -278,7 +278,7 @@ const defaultOptions = { xmlMode: true };
  * Parse a feed.
  *
  * @param feed The feed that should be parsed, as a string.
- * @param options Optionally, options for parsing. When using this option, you probably want to set `xmlMode` to `true`.
+ * @param options Optionally, options for parsing. When using this option, you should set `xmlMode` to `true`.
  */
 export function parseFeed(
     feed: string,

src/Parser.ts

@@ -100,37 +100,49 @@ const htmlIntegrationElements = new Set([
 
 export interface ParserOptions {
     /**
-     * Indicates whether special tags (<script>, <style>, and <title>) should get special treatment
-     * and if "empty" tags (eg. <br>) can have children.  If `false`, the content of special tags
+     * Indicates whether special tags (`<script>`, `<style>`, and `<title>`) should get special treatment
+     * and if "empty" tags (eg. `<br>`) can have children.  If `false`, the content of special tags
      * will be text only. For feeds and other XML content (documents that don't consist of HTML),
-     * set this to `true`. Default: `false`.
+     * set this to `true`.
+     *
+     * @default false
      */
     xmlMode?: boolean;
 
     /**
-     * Decode entities within the document. Defaults to `true`.
+     * Decode entities within the document.
+     *
+     * @default true
      */
     decodeEntities?: boolean;
 
     /**
-     * If set to true, all tags will be lowercased. If xmlMode is disabled, this defaults to `true`.
+     * If set to true, all tags will be lowercased.
+     *
+     * @default !xmlMode
      */
     lowerCaseTags?: boolean;
 
     /**
-     * If set to `true`, all attribute names will be lowercased. This has noticeable impact on speed, so it defaults to `false`.
+     * If set to `true`, all attribute names will be lowercased. This has noticeable impact on speed.
+     *
+     * @default !xmlMode
      */
     lowerCaseAttributeNames?: boolean;
 
     /**
      * If set to true, CDATA sections will be recognized as text even if the xmlMode option is not enabled.
      * NOTE: If xmlMode is set to `true` then CDATA sections will always be recognized as text.
+     *
+     * @default xmlMode
      */
     recognizeCDATA?: boolean;
 
     /**
      * If set to `true`, self-closing tags will trigger the onclosetag event even if xmlMode is not set to `true`.
      * NOTE: If xmlMode is set to `true` then self-closing tags will always be recognized.
+     *
+     * @default xmlMode
      */
     recognizeSelfClosing?: boolean;
 
@@ -428,7 +440,8 @@ export class Parser {
     }
 
     /**
-     * Parses a complete document and pushes it to the handler.
+     * Resets the parser, then parses a complete document and
+     * pushes it to the handler.
      *
      * @param data Document to parse.
      */

src/__fixtures__/test-helper.ts

@@ -3,6 +3,15 @@ import { CollectingHandler } from "../CollectingHandler";
 import fs from "fs";
 import path from "path";
 
+/**
+ * Write to the parser twice, once a bytes, once as
+ * a single blob.
+ *
+ * @internal
+ * @param handler Handler to execute.
+ * @param options Parsing options.
+ * @param data Data to write.
+ */
 export function writeToParser(
     handler: Partial<Handler>,
     options: ParserOptions | undefined,
@@ -23,7 +32,13 @@ interface Event {
     data: unknown[];
 }
 
-// Returns a tree structure
+/**
+ * Creates a `CollectingHandler` that calls the supplied
+ * callback with simplified events on completion.
+ *
+ * @internal
+ * @param cb Function to call with all events.
+ */
 export function getEventCollector(
     cb: (error: Error | null, events?: Event[]) => void
 ): CollectingHandler {
@@ -65,6 +80,12 @@ function eventReducer(
     return events;
 }
 
+/**
+ * Runs a test suite twice, ensuring input data matches expectations.
+ *
+ * @param file Test file to execute.
+ * @param done Function to call on completion.
+ */
 function getCallback(file: TestFile, done: (err?: Error | null) => void) {
     let repeated = false;
 
@@ -92,6 +113,14 @@ interface TestFile {
     expected?: unknown | unknown[];
 }
 
+/**
+ * Creates a test suite for a particular directory, with
+ * a specified test function.
+ *
+ * @internal
+ * @param name Name of the test directory.
+ * @param getResult Function to be called with the actual results.
+ */
 export function createSuite(
     name: string,
     getResult: (