feat(tsdoc): add tsdocs for parsers

.releaserc.json

@@ -4,11 +4,7 @@
       "@semantic-release/commit-analyzer",
       {
         "preset": "angular",
-        "releaseRules": [
-          { "type": "docs", "scope": "readme", "release": "patch" },
-          { "type": "docs", "scope": "tsdoc", "release": "patch" },
-          { "scope": "no-release", "release": false }
-        ]
+        "releaseRules": [{ "scope": "no-release", "release": false }]
       }
     ],
     "@semantic-release/release-notes-generator",

docs/content/parsers/oneOf.md

@@ -1,7 +1,7 @@
 ---
 title: 'oneOf'
 kind: 'primitive'
-description: 'oneOf tries to match one of the characters in the given string.'
+description: 'oneOf ensures that one of the characters in the given string matches the current character.'
 ---
 
 ```typescript {{ withLineNumbers: false }}
@@ -10,7 +10,7 @@ function oneOf(): Parser<string>
 
 ## Description
 
-`oneOf` tries to match one of the characters in the given string.
+`oneOf` ensures that one of the characters in the given string matches the current character.
 
 ## Usage
 

src/parsers/any.ts

@@ -1,5 +1,10 @@
 import { type Parser } from '../state'
 
+/**
+ * Parses any single character from the input and returns it. Fails at the end of input.
+ *
+ * @returns A single parsed character.
+ */
 export function any(): Parser<string> {
   return {
     parse(input, pos) {

src/parsers/defer.ts

@@ -1,9 +1,61 @@
 import { type Parser } from '../state'
 
+/**
+ * Intersection type to add a method for deferred parser definition.
+ *
+ * @internal
+ */
 type Deferred<T> = Parser<T> & {
   with(parser: Parser<T>): void
 }
 
+/**
+ * This is a special parser that has an additional `with` method, which should be used to define the
+ * parser. This parser is tailored for creating mutually recursive parsers.
+ *
+ * @example
+ *
+ * ```typescript
+ * interface NumberNode {
+ *   type: 'number'
+ *   value: number
+ * }
+ *
+ * interface ListNode {
+ *   type: 'list'
+ *   value: Array<NumberNode | ListNode>
+ * }
+ *
+ * // Here we create 'dummies'
+ *
+ * const TupleList = defer<ListNode>()
+ * const TupleNumber = defer<NumberNode>()
+ *
+ * // And below we actually define parsers
+ *
+ * TupleNumber.with(
+ *   map(
+ *     int(),
+ *     (value) => ({ type: 'number', value })
+ *   )
+ * )
+ *
+ * TupleList.with(
+ *   map(
+ *     takeMid(
+ *       string('('),
+ *       sepBy(choice(TupleList, TupleNumber), string(',')),
+ *       string(')')
+ *     ),
+ *     (value) => ({ type: 'list', value })
+ *   )
+ * )
+ *
+ * console.log(
+ *   run(TupleList).with('(1,2,(3,(4,5)))')
+ * )
+ * ```
+ */
 export function defer<T>(): Deferred<T> {
   let deferred: Parser<T> | null = null
 

src/parsers/eof.ts

@@ -1,5 +1,10 @@
 import { type Parser } from '../state'
 
+/**
+ * Only succeeds at the end of the input.
+ *
+ * @returns `null`
+ */
 export function eof(): Parser<null> {
   return {
     parse(input, pos) {

src/parsers/eol.ts

@@ -7,6 +7,11 @@ import { string } from './string'
 const EOL_UNIX = '\n'
 const EOL_NON_UNIX = '\r\n'
 
+/**
+ * Only succeeds at the end of the line, either `\n` or `\r\n`.
+ *
+ * @returns Matched line break character
+ */
 export function eol(): Parser<string> {
   return error(choice(string(EOL_UNIX), string(EOL_NON_UNIX)), 'end of line')
 }

src/parsers/float.ts

@@ -4,6 +4,11 @@ import { regexp } from './regexp'
 
 const FLOAT_RE = /-?\d+\.\d+/g
 
+/**
+ * Parses a floating point number.
+ *
+ * @returns Parsed float as a number
+ */
 export function float(): Parser<number> {
   return {
     parse(input, pos) {

src/parsers/letter.ts

@@ -5,10 +5,20 @@ import { regexp } from './regexp'
 const LETTER_RE = /\p{Letter}/gu
 const LETTERS_RE = /\p{Letter}+/gu
 
+/**
+ * Parses a single alphabetical character. Unicode friendly.
+ *
+ * @returns Matched character.
+ */
 export function letter(): Parser<string> {
   return regexp(LETTER_RE, 'letter')
 }
 
+/**
+ * Parses a sequence of alphabetical characters. Unicode friendly.
+ *
+ * @returns Matched characters as a string.
+ */
 export function letters(): Parser<string> {
   return regexp(LETTERS_RE, 'letters')
 }

src/parsers/noneOf.ts

@@ -1,5 +1,12 @@
 import { type Parser } from '../state'
 
+/**
+ * Ensures that none of the characters in the given string matches the current character.
+ *
+ * @param chars - A string of characters that current character should not match
+ *
+ * @returns Current character
+ */
 export function noneOf(chars: string): Parser<string> {
   const charset = [...chars]
 

src/parsers/nothing.ts

@@ -1,5 +1,10 @@
 import { type Parser } from '../state'
 
+/**
+ * Simply resolves to `null`.
+ *
+ * @returns `null`.
+ */
 export function nothing(): Parser<null> {
   return {
     parse(_, pos) {

src/parsers/oneOf.ts

@@ -1,5 +1,12 @@
 import { type Parser } from '../state'
 
+/**
+ * Ensures that one of the characters in the given string matches the current character.
+ *
+ * @param chars - A string of characters that current character should match
+ *
+ * @returns Current character
+ */
 export function oneOf(chars: string): Parser<string> {
   const charset = [...chars]
 

src/parsers/regexp.ts

@@ -1,5 +1,20 @@
 import { type Parser } from '../state'
 
+/**
+ * Parses a string that matches a provided `re` regular expression. Returns the matched string, or
+ * fails with an `expected` message.
+ *
+ * The regular expression must obey three simple rules:
+ *
+ * - It *does* use `g` flag. Flags like `u` and `i` are allowed and can be added if needed.
+ * - It *doesn't* use `^` and `$` to match at the beginning or at the end of the text.
+ * - It *doesn't* use capturing groups.
+ *
+ * @param re - Regular expression
+ * @param expected - Error message if the regular expression does not match input
+ *
+ * @returns Matched string
+ */
 export function regexp(re: RegExp, expected: string): Parser<string> {
   return {
     parse(input, pos) {

src/parsers/rest.ts

@@ -1,5 +1,10 @@
 import { type Parser } from '../state'
 
+/**
+ * Simply returns the unparsed input as a string. Never fails.
+ *
+ * @returns Rest of the input as a string
+ */
 export function rest(): Parser<string> {
   return {
     parse(input, pos) {

src/parsers/run.ts

@@ -1,9 +1,20 @@
 import type { Parser, Result } from '../state'
 
+/**
+ * @internal
+ */
 interface Runnable<T> {
   with(input: string): Result<T>
 }
 
+/**
+ * Runs a parser with provided input.
+ *
+ * @typeParam T - Type of parser's result
+ * @param parser - Parser to run
+ *
+ * @returns Parser result
+ */
 export function run<T>(parser: Parser<T>): Runnable<T> {
   return {
     with(input) {

src/parsers/string.ts

@@ -1,6 +1,13 @@
 import { type Parser } from '../state'
 import { size } from '../utils/unicode'
 
+/**
+ * Parses an *ASCII* string. For parsing Unicode strings, consider using `ustring`.
+ *
+ * @param match - String to parse
+ *
+ * @returns Parsed string
+ */
 export function string(match: string): Parser<string> {
   return {
     parse(input, pos) {
@@ -28,6 +35,13 @@ export function string(match: string): Parser<string> {
   }
 }
 
+/**
+ * Parses a Unicode string. For parsing ASCII-only strings, consider using `string`.
+ *
+ * @param match - String to parse
+ *
+ * @returns Parsed string
+ */
 export function ustring(match: string): Parser<string> {
   return {
     parse(input, pos) {

src/parsers/whitespace.ts

@@ -4,6 +4,11 @@ import { regexp } from './regexp'
 
 const WHITESPACE_REQUIRED_RE = /\s+/g
 
+/**
+ * Parses whitespace, either a single character or consecutive ones.
+ *
+ * @returns Matched whitespace character(s)
+ */
 export function whitespace(): Parser<string> {
   return regexp(WHITESPACE_REQUIRED_RE, 'whitespace')
 }