From fb90f825edce7f8a2403b17e60a632f8e5300f1f Mon Sep 17 00:00:00 2001 From: Joshua Bemenderfer Date: Tue, 21 Feb 2023 16:00:53 -0500 Subject: [PATCH] Finish adding JS API docs. --- docs/src/_includes/nodes/CodeExample.njk | 7 +- docs/src/docs/c.tce | 60 ++-- docs/src/docs/javascript.tce | 413 ++++++++++++++++------- docs/src/parser/nodes/CodeExample.js | 4 +- docs/tailwind.config.js | 7 + packages/js/src/parser.ts | 8 +- packages/js/src/readers/js-string.ts | 12 +- packages/js/src/readers/node-readline.ts | 38 ++- 8 files changed, 379 insertions(+), 170 deletions(-) diff --git a/docs/src/_includes/nodes/CodeExample.njk b/docs/src/_includes/nodes/CodeExample.njk index 28736aa..f0719d3 100644 --- a/docs/src/_includes/nodes/CodeExample.njk +++ b/docs/src/_includes/nodes/CodeExample.njk @@ -7,7 +7,8 @@ set languageMeta = { 'c': { name: 'C', icon: '' }, 'javascript': { name: 'JavaScript', icon: '' }, 'typescript': { name: 'TypeScript', icon: '' }, - 'python': { name: 'Python', icon: '' } + 'python': { name: 'Python', icon: '' }, + 'sh': { name: 'shell' } } %} @@ -26,7 +27,9 @@ set languageMeta = { h-12 {{ node.summaryClass }} " > - + {% if languageMeta[example.language].icon %} + + {% endif %} {{ example.name or languageMeta[example.language].name }} 
@@ -79,6 +79,30 @@ Section light
 
     Markdown
 
+    Heading 2 Core API
+      class mt-12
+
+    Heading 3 terrace_linedata_t
+      class my-6
+    CodeBlock c
+      // Holds the parsed information from each line.
+      typedef struct terrace_linedata_s {
+        // Which character is being used for indentation. Avoids having to specify it on each terrace_parse_line call.
+        char indent;
+        // How many indent characters are present in the current line before the first non-indent character.
+        unsigned int level;
+        // The number of characters before the start of the line's "head" section.
+        // (Normally the same as `level`)
+        unsigned int offsetHead;
+        // The number of characters before the start of the line's "tail" section.
+        unsigned int offsetTail;
+      } terrace_linedata_t;
+
+    Heading 3 terrace_parse_line()
+      class my-6
+    CodeBlock c
+      void terrace_parse_line(char* line, terrace_linedata_t *lineData)
+
     Heading 2 Recipes
       class mt-12
 
@@ -156,38 +180,6 @@ Section light
         free(line);
       }
 
-
-    Heading 2 Core API
-      class mt-12
-
-    Markdown
-      In most cases, you'll use the [Document API](#document-api) instead.
-      The Core API provides low-level parsing for individual lines.
-
-    Heading 3 terrace_linedata_t
-      class my-6
-    CodeBlock c
-      // Holds the parsed information from each line.
-      typedef struct terrace_linedata_s {
-        // Which character is being used for indentation. Avoids having to specify it on each terrace_parse_line call.
-        char indent;
-        // How many indent characters are present in the current line before the first non-indent character.
-        unsigned int level;
-        // The number of characters before the start of the line's "head" section.
-        // (Normally the same as `level`)
-        unsigned int offsetHead;
-        // The number of characters before the start of the line's "tail" section.
-        unsigned int offsetTail;
-      } terrace_linedata_t;
-
-    Heading 3 terrace_create_line_data()
-      class my-6
-
-    Heading 3 terrace_parse_line()
-      class my-6
-    CodeBlock c
-      void terrace_parse_line(char* line, terrace_linedata_t *lineData)
-
     Heading 2 Contributing
       class mt-12
 
diff --git a/docs/src/docs/javascript.tce b/docs/src/docs/javascript.tce
index eb24ae1..5b0f84e 100644
--- a/docs/src/docs/javascript.tce
+++ b/docs/src/docs/javascript.tce
@@ -11,15 +11,13 @@ Section light
     TableOfContents
 
   Block
-    class max-w-prose
-
     Heading 1 Terrace JavaScript Documentation
       class -ml-2
 
     Markdown
       Documentation is available for the following languages:
       - [C](/docs/c/) - 10% Complete
-      - [JavaScript](/docs/javascript/) - 50% Complete
+      - [JavaScript](/docs/javascript/) - 75% Complete
       - [Python](/docs/python/) - 0% Complete
 
     Heading 2 Getting Started
@@ -37,132 +35,86 @@ Section light
       # Yarn (https://yarnpkg.com/)
       $ yarn add @terrace-lang/js
 
-    Heading 2 Recipes
-      class mt-12
-
-    Heading 3 Read object properties
-      class mb-2
-    Markdown
-      Read known properties from a Terrace block and write them to an object.
-    CodeBlock javascript
-      // Provides simple convenience functions over the core parser
-      // CommonJS: const { useDocument } = require('@terrace-lang/js/document')
-      import { useDocument } from '@terrace-lang/js/document'
-      // A helper for iterating over a string line-by-line
-      // CommonJS: const { createStringReader } = require('@terrace-lang/js/readers/js-string')
-      import { createStringReader } from '@terrace-lang/js/readers/js-string'
-
-      const input = `
-      object
-        string_property An example string
-        numeric_property An example property
-      `
-
-      const output = {
-        string_property: null,
-        numeric_property: null
-      }
-
-      // useDocument returns convenience functions
-      const { next, level, head, tail, match } = useDocument(createStringReader(input))
-
-      // next() parses the next line in the document
-      while (await next()) {
-        // match('object') is equivalent to head() === 'object'
-        // Essentially: "If the current line starts with 'object'"
-        if (match('object')) {
-          const objectLevel = level()
-          // When we call next with a parent level it,
-          // only iterates over lines inside the parent block
-          while (await next(objectLevel)) {
-            // tail() returns the part of the current line after the first space
-            if (match('string_property')) output.string_property = tail()
-            // parseFloat() here the string tail() to a numeric float value
-            if (match('numeric_property')) output.numeric_property = parseFloat(tail())
-          }
-        }
-      }
-
-      console.dir(output)
-
-    Markdown
-      Read *all* properties as strings from a Terrace block and write them to an object.
-    CodeBlock javascript
-      // Provides simple convenience functions over the core parser
-      // CommonJS: const { useDocument } = require('@terrace-lang/js/document')
-      import { useDocument } from '@terrace-lang/js/document'
-      // A helper for iterating over a string line-by-line
-      // CommonJS: const { createStringReader } = require('@terrace-lang/js/readers/js-string')
-      import { createStringReader } from '@terrace-lang/js/readers/js-string'
-
-      const input = `
-      object
-        property1 Value 1
-        property2 Value 2
-        random_property igazi3ii4quaC5OdoB5quohnah1beeNg
-      `
-
-      const output = {}
-
-      // useDocument returns convenience functions
-      const { next, level, head, tail, match } = useDocument(createStringReader(input))
-
-      // next() parses the next line in the document
-      while (await next()) {
-        // match('object') is equivalent to head() === 'object'
-        // Essentially: "If the current line starts with 'object'"
-        if (match('object')) {
-          const objectLevel = level()
-          // When we call next with a parent level it,
-          // only iterates over lines inside the parent block
-          while (await next(objectLevel)) {
-            // Skip empty lines
-            if (!line()) continue
-            // Add any properties to the object as strings using the
-            // line head() as the key and tail() as the value
-            output[head()] = tail()
-          }
-        }
-      }
-
-      console.dir(output)
-
     Heading 2 Core API
       class mt-12
     Markdown
-      **TODO:** Document
+      **Note:** The Core API uses C-style conventions to optimize memory management
+      and improve portability to other environments and languages.
+      It is unwieldy and does not follow JavaScript best practices.
+
+      For most projects you'll want to use the [Document API](#document-api) instead.
+      It provides an ergonomic wrapper around the Core API and lets you focus on parsing
+      your documents.
 
     Heading 3 LineData
-      class my-6
+      class mb-4 mt-12
     CodeBlock typescript
       // Type Definition
+      // Holds the parsed information from each line.
       type LineData = {
-        line: string;
+        // Which character is being used for indentation. Avoids having to specify it on each parseLine call.
         indent: string;
+        // How many indent characters are present in the current line before the first non-indent character.
         level: number;
+        // The number of characters before the start of the line's "head" section.
+        // (Normally the same as `level`)
         offsetHead: number;
+        // The number of characters before the start of the line's "tail" section.
         offsetTail: number;
       }
 
     Heading 3 createLineData()
-      class my-6
+      class mb-4 mt-12
+    Markdown
+      | Parameter      | Type                  | Description
+      | -------------- | --------------------- | -----------------------------------------------------------------------
+      | indent         | string                | The character used for indentation in the document. Only a single character is permitted.
+      | **@returns**   | [LineData](#line-data) | A LineData instance with the specified indent character and all other values initialized to 0.
+
+      Initialize a LineData instance with default values to pass to [parseLine()](#parse-line).
+
     CodeBlock typescript
-      function createLineData(line: string = '', indent: string = ' '): LineData
-    CodeBlock javascript
+      // Type Definition
+      function createLineData(indent: string = ' '): LineData
+
+      // Import Path
       import { createLineData } from '@terrace-lang/js/parser'
 
+      // Usage
+      const lineData = createLineData(' ')
+      console.dir(lineData)
+      // { indent: ' ', level: 0, offsetHead: 0, offsetTail: 0 }
+      // Use the same lineData object for all calls to parseLine in the same document.
+
     Heading 3 parseLine()
-      class my-6
+      class mb-4 mt-12
+    Markdown
+      | Parameter      | Type                  | Description
+      | -------------- | --------------------- | -----------------------------------------------------------------------
+      | line         | string                  | A string containing a line to parse. Shouldn't end with a newline.
+      | lineData     | [LineData](#line-data)  | A LineData object to store information about the current line, from [createLineData()](#create-line-data).
**Mutated in-place!**
+
+      Core Terrace parser function, sets `level`, `offsetHead`, and `offsetTail` in a [LineData](#line-data) object based on the passed line.
+      Note that this is a C-style function, `lineData` is treated as a reference and mutated in-place.
+
     CodeBlock typescript
+      // Type Definition
       function parseLine(lineData: LineData): LineData
-    CodeBlock javascript
-      import { parseLine } from '@terrace-lang/js/parser'
+
+      // Import Path
+      import { createLineData, parseLine } from '@terrace-lang/js/parser'
+
+      // Usage
+      const lineData = createLineData(' ')
+      parseLine('title Example Title', lineData)
+      console.dir(lineData)
+      // { indent: ' ', level: 0, offsetHead: 0, offsetTail: 5 }
 
     Heading 2 Document API
       class mt-12
 
     Heading 3 useDocument()
-      class my-6
+      class mb-4 mt-12
     Markdown
       | Parameter      | Type                  | Description
       | -------------- | --------------------- | -----------------------------------------------------------------------
@@ -179,7 +131,7 @@ Section light
       import { useDocument } from '@terrace-lang/js/document'
 
     Heading 3 Document
-      class my-6
+      class mb-4 mt-12
     Markdown
       Container for a handful of convenience functions for parsing documents.
       Obtained from [useDocument()](#usedocument) above
@@ -195,7 +147,7 @@ Section light
       }
 
     Heading 3 Document.next()
-      class my-6
+      class mb-4 mt-12
 
     Markdown
       | Parameter      | Type                  | Description
@@ -230,7 +182,7 @@ Section light
       }
 
     Heading 3 Document.level()
-      class my-6
+      class mb-4 mt-12
     Markdown
       | Parameter      | Type                  | Description
       | -------------- | --------------------- | -----------------------------------------------------------------------
@@ -254,7 +206,7 @@ Section light
       const { level } = useDocument(...)
 
     Heading 3 Document.line()
-      class my-6
+      class mb-4 mt-12
     Markdown
       | Parameter      | Type                  | Description
       | -------------- | --------------------- | -----------------------------------------------------------------------
@@ -282,7 +234,7 @@ Section light
       const { line } = useDocument(...)
 
     Heading 3 Document.head()
-      class my-6
+      class mb-4 mt-12
     Markdown
       | Parameter      | Type                  | Description
       | -------------- | --------------------- | -----------------------------------------------------------------------
@@ -305,7 +257,7 @@ Section light
       const { head } = useDocument(...)
 
     Heading 3 Document.tail()
-      class my-6
+      class mb-4 mt-12
     Markdown
       | Parameter      | Type                  | Description
       | -------------- | --------------------- | -----------------------------------------------------------------------
@@ -327,7 +279,7 @@ Section light
       const { tail } = useDocument(...)
 
     Heading 3 Document.match()
-      class my-6
+      class mb-4 mt-12
     Markdown
       | Parameter      | Type                  | Description
       | -------------- | --------------------- | -----------------------------------------------------------------------
@@ -355,25 +307,69 @@ Section light
     Heading 2 Reader API
       class mt-12
     Markdown
-      **TODO:** Document
+      The [Document API](#document-api) requires `Reader` functions to iterate through lines
+      in a document. A reader function simply returns a string (or a promise resolving to a string).
+      Each time it is called, it returns the next line from whichever source it is pulling them.
+
+      Terrace provides a few built-in readers, but you are welcome to build your own instead.
 
     Heading 3 Reader
-      class my-6
+      class mb-4 mt-12
+    Markdown
+      Any function (async included) that returns the next line in a document when called and null when the end of the document has been reached.
+
     CodeBlock typescript
       // Type Definition
       type Reader = () => string|null|Promise
 
     Heading 3 createStringReader()
-      class my-6
+      class mb-4 mt-12
+    Markdown
+      | Parameter      | Type                  | Description
+      | -------------- | --------------------- | -----------------------------------------------------------------------
+      | source         | string\|string[]      | The lines to iterate over, as a multiline string or an array of line strings.
+      | index          | number                | Optional - which line to start from.
+      | **@returns**   | [Reader](#reader)     | A reader function that returns each line from the source document when called sequentially.
+
+      Get a simple [Reader](#reader) function that always returns the next line from a mutliline string or an array of line strings.
     CodeBlock typescript
       // Type Definition
-      function createStringReader(path: string): Reader
+      function createStringReader(source: string|string[], index: number = 0): Reader
 
       // Import Path
       import { createStringReader } from '@terrace-lang/js/readers/js-string'
 
+    Markdown
+      **Usage**
+    CodeBlock typescript
+      import { createStringReader, useDocument } from '@terrace-lang/js'
+
+      // Create a string reader with two lines
+      const reader = createStringReader('title Example Title\n line2')
+      // Also permitted:
+      // const reader = createStringReader(['title Example Title', ' line 2'])
+
+      const { next, level, line } = useDocument(reader)
+      await next()
+      console.log(level(), line())
+      // 0 title Example Title
+      await next()
+      console.log(level(), line())
+      // 1 line 2
+
+
     Heading 3 createFileReader()
-      class my-6
+      class mb-4 mt-12
+    Markdown
+      | Parameter      | Type                  | Description
+      | -------------- | --------------------- | -----------------------------------------------------------------------
+      | path         | string                  | A path to the file to read.
+      | **@returns**   | [Reader](#reader)     | A reader function that returns each line from the file when called sequentially
+
+      **Note:** Only available in Node.js environments.

+      Get a [Reader](#reader) function that returns the next line from the specified file when called sequentially.
+
+
     CodeBlock typescript
       // Type Definition
       function createFileReader(path: string): Reader
@@ -381,14 +377,199 @@ Section light
       // Import Path
       import { createFileReader } from '@terrace-lang/js/readers/node-readline'
 
+    Markdown
+      **Usage**
+    CodeExample
+      summary-class mb-[300px]
+      pre-class max-h-[300px]
+      javascript main.js
+        import { createFileReader, useDocument } from '@terrace-lang/js'
+
+        // Read the file ./example.tce
+        const { next, level, line } = useDocument(createFileReader('./example.tce'))
+        await next()
+        console.log(level(), line())
+        // 0 title Example Title
+        await next()
+        console.log(level(), line())
+        // 1 line 2
+
+      terrace example.tce
+        title Example Title
+         line 2
+
     Heading 3 createStdinReader()
-      class my-6
+      class mb-4 mt-12
+    Markdown
+      | Parameter      | Type                  | Description
+      | -------------- | --------------------- | -----------------------------------------------------------------------
+      | **@returns**   | [Reader](#reader)     | A reader function that returns each line from `stdin` when called sequentially
+
+      **Note:** Only available in Node.js environments.

+      Get a [Reader](#reader) function that returns the next line from standard input when called sequentially. Does not block stdin to wait for input. If no input is present it returns null immediately.
     CodeBlock typescript
       // Type Definition
       function createStdinReader(): Reader
 
       // Import Path
       import { createStdinReader } from '@terrace-lang/js/readers/node-readline'
+    Markdown
+      **Usage**
+    CodeExample
+      summary-class mb-[250px]
+      pre-class max-h-[250px]
+      javascript main.js
+        import { createStdinReader, useDocument } from '@terrace-lang/js'
+
+        // Read the contents of standard input
+        const { next, level, line } = useDocument(createStdinReader())
+
+        while(await next()) {
+          console.log(level(), line())
+          // See `shell` panel above for output
+        }
+
+      terrace example.tce
+        title Example Title
+         line 2
+
+      sh
+        # Run main.js with the contents of example.tce piped to stdin
+        $ cat example.tce > node ./main.js
+        0 title Example Title
+        1 line 2
+
+    Heading 3 createStreamReader()
+      class mb-4 mt-12
+    Markdown
+      | Parameter      | Type                  | Description
+      | -------------- | --------------------- | -----------------------------------------------------------------------
+      | stream         | NodeJS.ReadStream|fs.ReadStream | A ReadStream compatible with Node.js `readline` APIs
+      | **@returns**   | [Reader](#reader)     | A reader function that returns each line from `stdin` when called sequentially
+
+      **Note:** Only available in Node.js environments.

+      Get a [Reader](#reader) function that always returns the next line from a passed read stream when called sequentially.
+    CodeBlock typescript
+      // Type Definition
+      function createStreamReader(): Reader
+
+      // Import Path
+      import { createStreamReader } from '@terrace-lang/js/readers/node-readline'
+    Markdown
+      **Usage**
+    CodeExample
+      summary-class mb-[320px]
+      pre-class max-h-[320px]
+      javascript main.js
+        import fs from 'node:fs'
+        import { createStreamReader, useDocument } from '@terrace-lang/js'
+
+        // Read the file ./example.tce - equivalent to the `createFileReader` example above.
+        const reader = createStreamReader(fs.createReadStream('./example.tce'))
+        const { next, level, line } = useDocument(reader)
+        await next()
+        console.log(level(), line())
+        // 0 title Example Title
+        await next()
+        console.log(level(), line())
+        // 1 line 2
+
+      terrace example.tce
+        title Example Title
+         line 2
+
+    Heading 2 Recipes
+      class mt-12
+
+    Heading 3 Read object properties
+      class mb-2
+    Markdown
+      Read known properties from a Terrace block and write them to an object.
+    CodeBlock javascript
+      // Provides simple convenience functions over the core parser
+      // CommonJS: const { useDocument } = require('@terrace-lang/js/document')
+      import { useDocument } from '@terrace-lang/js/document'
+      // A helper for iterating over a string line-by-line
+      // CommonJS: const { createStringReader } = require('@terrace-lang/js/readers/js-string')
+      import { createStringReader } from '@terrace-lang/js/readers/js-string'
+
+      const input = `
+      object
+        string_property An example string
+        numeric_property 4
+      `
+
+      const output = {
+        string_property: null,
+        numeric_property: null
+      }
+
+      // useDocument returns convenience functions
+      const { next, level, head, tail, match } = useDocument(createStringReader(input))
+
+      // next() parses the next line in the document
+      while (await next()) {
+        // match('object') is equivalent to head() === 'object'
+        // Essentially: "If the current line starts with 'object'"
+        if (match('object')) {
+          const objectLevel = level()
+          // When we call next with a parent level it,
+          // only iterates over lines inside the parent block
+          while (await next(objectLevel)) {
+            // tail() returns the part of the current line after the first space
+            if (match('string_property')) output.string_property = tail()
+            // parseFloat() here the string tail() to a numeric float value
+            if (match('numeric_property')) output.numeric_property = parseFloat(tail())
+          }
+        }
+      }
+
+      console.dir(output)
+      // { string_property: 'An example string', numeric_property: 4 }
+
+    Markdown
+      Read *all* properties as strings from a Terrace block and write them to an object.
+    CodeBlock javascript
+      // Provides simple convenience functions over the core parser
+      // CommonJS: const { useDocument } = require('@terrace-lang/js/document')
+      import { useDocument } from '@terrace-lang/js/document'
+      // A helper for iterating over a string line-by-line
+      // CommonJS: const { createStringReader } = require('@terrace-lang/js/readers/js-string')
+      import { createStringReader } from '@terrace-lang/js/readers/js-string'
+
+      const input = `
+      object
+        property1 Value 1
+        property2 Value 2
+        random_property igazi3ii4quaC5OdoB5quohnah1beeNg
+      `
+
+      const output = {}
+
+      // useDocument returns convenience functions
+      const { next, level, head, tail, match } = useDocument(createStringReader(input))
+
+      // next() parses the next line in the document
+      while (await next()) {
+        // match('object') is equivalent to head() === 'object'
+        // Essentially: "If the current line starts with 'object'"
+        if (match('object')) {
+          const objectLevel = level()
+          // When we call next with a parent level,
+          // it only iterates over lines inside the parent block
+          while (await next(objectLevel)) {
+            // Skip empty lines
+            if (!line()) continue
+            // Add any properties to the object as strings using the
+            // line head() as the key and tail() as the value
+            output[head()] = tail()
+          }
+        }
+      }
+
+      console.dir(output)
+      // { property1: 'Value 1', property2: 'Value 2', random_property: 'igazi3ii4quaC5OdoB5quohnah1beeNg' }
+
 
     Heading 2 Contributing
       class mt-12
diff --git a/docs/src/parser/nodes/CodeExample.js b/docs/src/parser/nodes/CodeExample.js
index bf7dd1e..78fce85 100644
--- a/docs/src/parser/nodes/CodeExample.js
+++ b/docs/src/parser/nodes/CodeExample.js
@@ -1,6 +1,6 @@
 const { contentAsText } = require('../helpers')
 
-const languages = ['terrace', 'json', 'yaml', 'toml', 'javascript', 'typescript', 'c', 'python']
+const languages = ['terrace', 'json', 'yaml', 'toml', 'javascript', 'typescript', 'c', 'python', 'sh']
 
 module.exports = async (doc, rootLevel) => {
   const { next, level, line, head, tail, match } = doc
@@ -23,7 +23,7 @@ module.exports = async (doc, rootLevel) => {
       node.examples.push({
         language: head(),
         name: tail() || '',
-        code: await contentAsText(doc, exampleLevel)
+        code: (await contentAsText(doc, exampleLevel)).trimEnd('\n')
       })
     }
   }
diff --git a/docs/tailwind.config.js b/docs/tailwind.config.js
index cb7dba0..b80b944 100644
--- a/docs/tailwind.config.js
+++ b/docs/tailwind.config.js
@@ -51,6 +51,13 @@ module.exports = {
       fontFamily: {
         sans: ['Fredoka', ...defaultTheme.fontFamily.sans],
       },
+      typography: {
+        DEFAULT: {
+          css: {
+            maxWidth: '80ch'
+          }
+        }
+      }
     },
   },
   variants: {},
diff --git a/packages/js/src/parser.ts b/packages/js/src/parser.ts
index 61f544f..3c5cba4 100644
--- a/packages/js/src/parser.ts
+++ b/packages/js/src/parser.ts
@@ -1,6 +1,6 @@
 // Holds the parsed information from each line.
 export type LineData = {
-  // Which character is being used for indentation. Avoids having to specify it on each terrace_parse_line call.
+  // Which character is being used for indentation. Avoids having to specify it on each parseLine call.
   indent: string;
   // How many indent characters are present in the current line before the first non-indent character.
   level: number;
@@ -12,7 +12,7 @@ export type LineData = {
 }
 
 /**
- * Initialize a LineData instance with default values.
+ * Initialize a LineData instance with default values to pass to parseLine()
  * @param {string} indent The character to use for indenting lines. ONLY ONE CHARACTER IS CURRENTLY PERMITTED.
  * @returns {LineData} A LineData instance with the specified indent character and all other values initialized to 0.
  */
@@ -21,10 +21,10 @@ export function createLineData(indent: string = ' '): LineData {
 }
 
 /**
- * Core Terrace parser function, sets level, offsetHead, and offsetTail in a LineData object based on the current line.
+ * Core Terrace parser function, sets level, offsetHead, and offsetTail in a LineData object based on the passed line.
  * Note that this is a C-style function, lineData is treated as a reference and mutated in-place.
  * @param {string} line A string containing a line to parse. Shouldn't end with a newline.
- * @param {LineData} lineData A LineData object to store information about the current line in. **Mutated in-place!**
+ * @param {LineData} lineData A LineData object to store information about the current line, from `createLineData()` **Mutated in-place!**
  */
 export function parseLine(line: string, lineData: LineData) {
   if ((typeof lineData !== 'object' || !lineData) || typeof lineData.level !== 'number') throw new Error(`'lineData' must be an object with string line and numeric level properties`)
diff --git a/packages/js/src/readers/js-string.ts b/packages/js/src/readers/js-string.ts
index 879159a..d8deda3 100644
--- a/packages/js/src/readers/js-string.ts
+++ b/packages/js/src/readers/js-string.ts
@@ -1,7 +1,15 @@
 import type { Reader } from './reader'
 
-export function createStringReader(doc: string|string[], index = 0): Reader {
-  const lines = Array.isArray(doc) ? doc : doc.split('\n')
+/**
+ * Get a simple `Reader` function that always returns the next line
+ * from a multiline string or an array of line strings.
+ *
+ * @param {string|string[]} source The lines to iterate over, as a multiline string or an array of line strings.
+ * @param {number} index Optional - which line to start from.
+ * @returns {Reader} A reader function that returns each line from the source document when called sequentially.
+ */
+export function createStringReader(source: string|string[], index: number = 0): Reader {
+  const lines = Array.isArray(source) ? source : source.split('\n')
 
   index--;
 
diff --git a/packages/js/src/readers/node-readline.ts b/packages/js/src/readers/node-readline.ts
index 99c5191..3afbb61 100644
--- a/packages/js/src/readers/node-readline.ts
+++ b/packages/js/src/readers/node-readline.ts
@@ -2,18 +2,36 @@ import fs from 'node:fs'
 import readline from 'node:readline/promises'
 import type { Reader } from './reader'
 
+
+/**
+ * Get a `Reader` function that always returns the next line from a passed read stream when called sequentially.
+ * @param {NodeJS.ReadStream|fs.ReadStream} stream A ReadStream compatible with Node.js `readline` APIs
+ * @returns {Reader} A reader function that returns each line from the stream when called sequentially
+ */
+export function createStreamReader(stream: NodeJS.ReadStream|fs.ReadStream): Reader {
+  // A bit of a messy way of working with readline, but the most straightforward
+  // way I found that allowed pulling lines with a promise-style interface.
+  const iterator = readline.createInterface({
+    input: stream
+  })[Symbol.asyncIterator]()
+
+  return async () => (await iterator.next()).value
+}
+
+/**
+ * Get a `Reader` function that always returns the next line from the specified file when called sequentially.
+ * @param {string} path A path to the file to read.
+ * @returns {Reader} A reader function that returns each line from the file when called sequentially
+ */
 export function createFileReader(path: string): Reader {
-  const it = readline.createInterface({
-    input: fs.createReadStream(path, 'utf-8'),
-  })[Symbol.asyncIterator]()
-
-  return async () => (await it.next()).value
+  return createStreamReader(fs.createReadStream(path, 'utf-8'))
 }
 
+/**
+ * Get a `Reader` function that always returns the next line from `stdin` when called sequentially.
+ * Does not block stdin to wait for input. If no input is present it returns null immediately.
+ * @returns {Reader} A reader function that returns each line from the stdin when called sequentially.
+ */
 export function createStdinReader(): Reader {
-  const it = readline.createInterface({
-    input: process.stdin
-  })[Symbol.asyncIterator]()
-
-  return async () => (await it.next()).value
+  return createStreamReader(process.stdin)
 }