docs: add tsdocs for exposed utilities

examples/README.md

@@ -0,0 +1,4 @@
+See higher level packages for examples:
+
+- [@prismicio/helpers](https://github.com/prismicio/prismic-helpers/tree/master/examples)
+- [@prismicio/react](https://github.com/prismicio/prismic-react/tree/master/examples)

package.json

@@ -1,66 +1,66 @@
 {
-  "name": "@prismicio/richtext",
-  "version": "0.0.0",
-  "description": "A parser and serializer for Prismic's Rich Text format.",
-  "keywords": [
-    "typescript",
-    "prismic"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "ssh://git@github.com/prismicio/prismic-richtext.git"
-  },
-  "license": "Apache-2.0",
-  "author": "Prismic <contact@prismic.io> (https://prismic.io)",
-  "type": "module",
-  "exports": {
-    ".": {
-      "require": "./dist/index.cjs",
-      "import": "./dist/index.mjs"
-    },
-    "./package.json": "./package.json"
-  },
-  "main": "dist/index.cjs",
-  "module": "dist/index.mjs",
-  "types": "dist/index.d.ts",
-  "files": [
-    "dist",
-    "src"
-  ],
-  "scripts": {
-    "build": "siroc build",
-    "dev": "siroc build --watch",
-    "format": "prettier --write .",
-    "prepare": "npm run build",
-    "release": "npm run build && npm run test && standard-version && git push --follow-tags && npm run build && npm publish",
-    "release:dry": "standard-version --dry-run",
-    "release:alpha": "npm run build && npm run test && standard-version --release-as major --prerelease alpha && git push --follow-tags && npm run build && npm publish --tag alpha",
-    "release:alpha:dry": "standard-version --release-as major --prerelease alpha --dry-run",
-    "lint": "eslint --ext .js,.ts .",
-    "unit": "nyc --reporter=lcovonly --reporter=text --exclude-after-remap=false ava",
-    "test": "npm run lint && npm run unit"
-  },
-  "dependencies": {
-    "@prismicio/types": "^0.0.10"
-  },
-  "devDependencies": {
-    "@typescript-eslint/eslint-plugin": "^4.28.0",
-    "@typescript-eslint/parser": "^4.28.0",
-    "ava": "^3.15.0",
-    "eslint": "^7.29.0",
-    "eslint-config-prettier": "^8.3.0",
-    "eslint-plugin-prettier": "^3.4.0",
-    "nyc": "^15.1.0",
-    "prettier": "^2.3.1",
-    "siroc": "^0.11.0",
-    "standard-version": "^9.3.0",
-    "ts-eager": "^2.0.2",
-    "typescript": "^4.3.4"
-  },
-  "engines": {
-    "node": ">=12.7.0"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
+	"name": "@prismicio/richtext",
+	"version": "0.0.0",
+	"description": "A parser and serializer for Prismic's Rich Text format",
+	"keywords": [
+		"typescript",
+		"prismic"
+	],
+	"repository": {
+		"type": "git",
+		"url": "ssh://git@github.com/prismicio/prismic-richtext.git"
+	},
+	"license": "Apache-2.0",
+	"author": "Prismic <contact@prismic.io> (https://prismic.io)",
+	"type": "module",
+	"exports": {
+		".": {
+			"require": "./dist/index.cjs",
+			"import": "./dist/index.mjs"
+		},
+		"./package.json": "./package.json"
+	},
+	"main": "dist/index.cjs",
+	"module": "dist/index.mjs",
+	"types": "dist/index.d.ts",
+	"files": [
+		"dist",
+		"src"
+	],
+	"scripts": {
+		"build": "siroc build",
+		"dev": "siroc build --watch",
+		"format": "prettier --write .",
+		"prepare": "npm run build",
+		"release": "npm run build && npm run test && standard-version && git push --follow-tags && npm run build && npm publish",
+		"release:dry": "standard-version --dry-run",
+		"release:alpha": "npm run build && npm run test && standard-version --release-as major --prerelease alpha && git push --follow-tags && npm run build && npm publish --tag alpha",
+		"release:alpha:dry": "standard-version --release-as major --prerelease alpha --dry-run",
+		"lint": "eslint --ext .js,.ts .",
+		"unit": "nyc --reporter=lcovonly --reporter=text --exclude-after-remap=false ava",
+		"test": "npm run lint && npm run unit"
+	},
+	"dependencies": {
+		"@prismicio/types": "^0.0.10"
+	},
+	"devDependencies": {
+		"@typescript-eslint/eslint-plugin": "^4.28.0",
+		"@typescript-eslint/parser": "^4.28.0",
+		"ava": "^3.15.0",
+		"eslint": "^7.29.0",
+		"eslint-config-prettier": "^8.3.0",
+		"eslint-plugin-prettier": "^3.4.0",
+		"nyc": "^15.1.0",
+		"prettier": "^2.3.1",
+		"siroc": "^0.11.1",
+		"standard-version": "^9.3.0",
+		"ts-eager": "^2.0.2",
+		"typescript": "^4.3.4"
+	},
+	"engines": {
+		"node": ">=12.7.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
 }

src/RichTextError.ts

@@ -1 +1,4 @@
+/**
+ * Errors thrown by @prismicio/richtext {@link https://github.com/prismicio/prismic-richtext}
+ */
 export class RichTextError extends Error {}

src/asText.ts

@@ -1,5 +1,15 @@
 import { RichTextField, RTTextNode } from "@prismicio/types";
 
+/**
+ * Serializes a rich text or title field to a plain text string
+ *
+ * @param richTextField - A rich text or title field from Prismic
+ * @param [separator] - Separator used to join each element, defaults to a space
+ *
+ * @returns Plain text equivalent of the provided rich text or title field
+ *
+ * @see Templating rich text and title fields from Prismic {@link https://prismic.io/docs/technologies/templating-rich-text-and-title-fields-javascript}
+ */
 export const asText = (
 	richTextField: RichTextField,
 	separator = " ",

src/asTree.ts

@@ -10,11 +10,23 @@ import {
 } from "@prismicio/types";
 import { RTAnyNode, Tree, TreeNode } from "./types";
 
-export const uuid = (): string => {
+const uuid = (): string => {
 	return (++uuid.i).toString();
 };
 uuid.i = 0;
 
+/**
+ * Parses a rich text or title field into a tree
+ *
+ * @param nodes - A rich text or title field from Prismic
+ *
+ * @returns Tree from given rich text or title field
+ *
+ * @remarks
+ *
+ * This is a low level helper mainly intended to be used by higher level packages
+ * Most users aren't expected to this function directly
+ */
 export const asTree = (nodes: RTNode[]): Tree => {
 	const preparedNodes = prepareNodes(nodes);
 

src/composeSerializers.ts

@@ -1,13 +1,32 @@
 import { RichTextError } from "./RichTextError";
 import { RichTextFunctionSerializer } from "./types";
 
-export const composeSerializers = <T>(
+/**
+ * Takes an array of serializers and returns a serializer applying
+ * provided serializers sequentially until a result is returned
+ *
+ * @param serializers - Serializers to compose
+ *
+ * @returns Composed serializer
+ *
+ * @typeParam SerializerReturnType - Return type of serializers
+ *
+ * @throws {@link RichTextError} when no values are returned by all provided serializers
+ *
+ * @remarks
+ *
+ * This is a low level helper mainly intended to be used by higher level packages
+ * Most users aren't expected to this function directly
+ */
+export const composeSerializers = <SerializerReturnType>(
 	...serializers: [
-		RichTextFunctionSerializer<T>,
-		...RichTextFunctionSerializer<T>[]
+		RichTextFunctionSerializer<SerializerReturnType>,
+		...RichTextFunctionSerializer<SerializerReturnType>[]
 	]
 ) => {
-	return (...args: Parameters<RichTextFunctionSerializer<T>>): T => {
+	return (
+		...args: Parameters<RichTextFunctionSerializer<SerializerReturnType>>
+	): SerializerReturnType => {
 		for (let i = 0; i < serializers.length; i++) {
 			const res = serializers[i](...args);
 

src/serialize.ts

@@ -2,11 +2,31 @@ import { RichTextField } from "@prismicio/types";
 import { RichTextFunctionSerializer, TreeNode } from "./types";
 import { asTree } from "./asTree";
 
-export const serialize = <T>(
+/**
+ * Serializes a rich text or title field with a given serializer
+ *
+ * @param richTextField - A rich text or title field from Prismic
+ * @param serializer - A function serializer to apply
+ *
+ * @returns An array of serialized nodes
+ *
+ * @typeParam SerializerReturnType - Return type of the serializer
+ *
+ * @see Templating rich text and title fields from Prismic {@link https://prismic.io/docs/technologies/templating-rich-text-and-title-fields-javascript}
+ *
+ * @remarks
+ *
+ * This is a low level helper mainly intended to be used by higher level packages
+ * Most users aren't expected to this function directly
+ */
+export const serialize = <SerializerReturnType>(
 	richTextField: RichTextField,
-	serializer: RichTextFunctionSerializer<T>,
-): T[] => {
-	return serializeTreeNodes(asTree(richTextField).children, serializer);
+	serializer: RichTextFunctionSerializer<SerializerReturnType>,
+): SerializerReturnType[] => {
+	return serializeTreeNodes<SerializerReturnType>(
+		asTree(richTextField).children,
+		serializer,
+	);
 };
 
 const serializeTreeNodes = <T>(