docs: improve TSDoc comments across codebase (#233)

* docs: simplify component descriptions

* docs: refine all TSDocs

* docs: clean up TSDocs

* style: run Prettier

* test: fix some ci error?

* test: fix imports

Author: angeloashmore

src/PrismicImage.tsx

@@ -29,7 +29,7 @@ export type PrismicImageProps = Omit<
 	ComponentProps<"img">,
 	"src" | "srcset" | "alt"
 > & {
-	/** The Prismic Image field or thumbnail to render. */
+	/** The Prismic image field or thumbnail to render. */
 	field: ImageFieldImage | null | undefined;
 
 	/**
@@ -48,7 +48,7 @@ export type PrismicImageProps = Omit<
 	alt?: "";
 
 	/**
-	 * Declare an image as decorative only if the Image field does not have
+	 * Declare an image as decorative only if the image field does not have
 	 * alternative text by providing `fallbackAlt=""`.
 	 *
 	 * See:
@@ -64,13 +64,13 @@ export type PrismicImageProps = Omit<
 } & (
 		| {
 				/**
-				 * Widths used to build a `srcset` value for the Image field.
+				 * Widths (in pixels) used to build a `srcset` value for the image
+				 * field.
 				 *
-				 * If a `widths` prop is not given or `"defaults"` is passed, the
-				 * following widths will be used: 640, 750, 828, 1080, 1200, 1920, 2048,
-				 * 3840.
+				 * If omitted or set to `"defaults"`, the following widths will be used:
+				 * 640, 750, 828, 1080, 1200, 1920, 2048, 3840.
 				 *
-				 * If the Image field contains responsive views, each responsive view
+				 * If the image field contains responsive views, each responsive view
 				 * can be used as a width in the resulting `srcset` by passing
 				 * `"thumbnails"` as the `widths` prop.
 				 */
@@ -84,7 +84,7 @@ export type PrismicImageProps = Omit<
 				/** Not used when the `widths` prop is used. */
 				widths?: never;
 				/**
-				 * Pixel densities used to build a `srcset` value for the Image field.
+				 * Pixel densities used to build a `srcset` value for the image field.
 				 *
 				 * If a `pixelDensities` prop is passed `"defaults"`, the following
 				 * pixel densities will be used: 1, 2, 3.
@@ -98,23 +98,15 @@ export type PrismicImageProps = Omit<
 	);
 
 /**
- * React component that renders an image from a Prismic Image field or one of
- * its thumbnails. It will automatically set the `alt` attribute using the Image
- * field's `alt` property.
+ * Renders an optimized image from a Prismic image field.
  *
- * By default, a widths-based srcset will be used to support responsive images.
- * This ensures only the smallest image needed for a browser is downloaded.
+ * @example
  *
- * To use a pixel-density-based srcset, use the `pixelDensities` prop. Default
- * pixel densities can be used by using `pixelDensities="defaults"`.
+ * ```tsx
+ * <PrismicImage field={slice.primary.photo} />;
+ * ```
  *
- * **Note**: If you are using a framework that has a native image component,
- * such as Next.js and Gatsby, prefer using those image components instead. They
- * can provide deeper framework integration than `<PrismicImage>`.
- *
- * @param props - Props for the component.
- *
- * @returns A responsive image component for the given Image field.
+ * @see Learn how to optimize images with imgix, use responsive images, and use framework-specific image components: {@link https://prismic.io/docs/fields/image}
  */
 export const PrismicImage: FC<PrismicImageProps> = forwardRef(
 	function PrismicImage(

src/PrismicLink.tsx

@@ -37,7 +37,7 @@ export interface LinkProps {
 	 */
 	rel?: string;
 
-	/** Children for the component. * */
+	/** Children for the component. */
 	children?: ReactNode;
 }
 
@@ -56,13 +56,13 @@ export type PrismicLinkProps<
 	rel?: string | AsLinkAttrsConfig["rel"];
 
 	/**
-	 * The Link Resolver used to resolve links.
+	 * The link resolver used to resolve links.
 	 *
 	 * @remarks
-	 * If your app uses Route Resolvers when querying for your Prismic
-	 * repository's content, a Link Resolver does not need to be provided.
+	 * If your app uses route resolvers when querying for your Prismic
+	 * repository's content, a link resolver does not need to be provided.
 	 *
-	 * @see Learn about Link Resolvers and Route Resolvers {@link https://prismic.io/docs/core-concepts/link-resolver-route-resolver}
+	 * @see Learn about link resolvers and route resolvers {@link https://prismic.io/docs/routes}
 	 */
 	linkResolver?: LinkResolverFunction;
 
@@ -100,6 +100,17 @@ export type PrismicLinkProps<
 		  }
 	);
 
+/**
+ * Renders a link from a Prismic link field or page.
+ *
+ * @example
+ *
+ * ```tsx
+ * <PrismicLink field={slice.primary.link}>Click here</PrismicLink>;
+ * ```
+ *
+ * @see Learn how to display links and use variants for styling: {@link https://prismic.io/docs/fields/link}
+ */
 export const PrismicLink = forwardRef(function PrismicLink<
 	InternalComponentProps = ComponentProps<typeof defaultComponent>,
 	ExternalComponentProps = ComponentProps<typeof defaultComponent>,

src/PrismicRichText.tsx

@@ -26,39 +26,39 @@ import { devMsg } from "./lib/devMsg.js";
 import { LinkProps, PrismicLink } from "./PrismicLink.js";
 
 /**
- * A function mapping Rich Text block types to React Components. It is used to
- * render Rich Text or Title fields.
+ * A function mapping rich text block types to React Components. It is used to
+ * render rich text fields.
  *
- * @see Templating rich text and title fields from Prismic {@link https://prismic.io/docs/technologies/templating-rich-text-and-title-fields-javascript}
+ * @see Templating rich text fields {@link https://prismic.io/docs/fields/rich-text}
  */
 export type JSXFunctionSerializer = RichTextFunctionSerializer<ReactNode>;
 
 /**
- * A map of Rich Text block types to React Components. It is used to render Rich
- * Text or Title fields.
+ * A map of rich text block types to React Components. It is used to render rich
+ * text fields.
  *
- * @see Templating Rich Text and Title fields from Prismic {@link https://prismic.io/docs/technologies/templating-rich-text-and-title-fields-javascript}
+ * @see Templating rich text fields {@link https://prismic.io/docs/fields/rich-text}
  */
 export type JSXMapSerializer = RichTextMapSerializer<ReactNode>;
 
 /** Props for `<PrismicRichText>`. */
 export type PrismicRichTextProps = {
-	/** The Prismic Rich Text field to render. */
+	/** The Prismic rich text field to render. */
 	field: RichTextField | null | undefined;
 
 	/**
-	 * The Link Resolver used to resolve links.
+	 * The link resolver used to resolve links.
 	 *
 	 * @remarks
-	 * If your app uses Route Resolvers when querying for your Prismic
-	 * repository's content, a Link Resolver does not need to be provided.
+	 * If your app uses route resolvers when querying for your Prismic
+	 * repository's content, a link resolver does not need to be provided.
 	 *
-	 * @see Learn about Link Resolvers and Route Resolvers {@link https://io/docs/core-concepts/link-resolver-route-resolver}
+	 * @see Learn about link resolvers and route resolvers {@link https://prismic.io/docs/routes}
 	 */
 	linkResolver?: LinkResolverFunction;
 
 	/**
-	 * A map or function that maps a Rich Text block to a React component.
+	 * A map or function that maps a rich text block to a React component.
 	 *
 	 * @remarks
 	 * Prefer using a map serializer over the function serializer when possible.
@@ -243,42 +243,15 @@ const createDefaultSerializer = (
 	});
 
 /**
- * React component that renders content from a Prismic Rich Text field. By
- * default, HTML elements are rendered for each piece of content. A `heading1`
- * block will render an `<h1>` HTML element, for example. Links will use
- * `<PrismicLink>` by default which can be customized using the
- * `internalLinkComponent` and `externalLinkComponent` props.
+ * Renders content from a Prismic rich text field as React components.
  *
- * To customize the components that are rendered, provide a map or function
- * serializer to the `components` prop.
+ * @example
  *
- * @remarks
- * This component returns a React fragment with no wrapping element around the
- * content. If you need a wrapper, add a component around `<PrismicRichText>`.
- *
- * @example Rendering a Rich Text field using the default HTMl elements.
- *
- * ```jsx
- * <PrismicRichText field={document.data.content} />;
+ * ```tsx
+ * <PrismicRichText field={slice.primary.text} />;
  * ```
  *
- * @example Rendering a Rich Text field using a custom set of React components.
- *
- * ```jsx
- * <PrismicRichText
- * 	field={document.data.content}
- * 	components={{
- * 		heading1: ({ children }) => <Heading>{children}</Heading>,
- * 	}}
- * />;
- * ```
- *
- * @param props - Props for the component.
- *
- * @returns The Rich Text field's content as React components.
- *
- * @see Learn about Rich Text fields {@link https://io/docs/core-concepts/rich-text-title}
- * @see Learn about Rich Text serializers {@link https://io/docs/core-concepts/html-serializer}
+ * @see Learn how to style rich text, use custom components, and use labels for custom formatting: {@link https://prismic.io/docs/fields/rich-text}
  */
 export const PrismicRichText: FC<PrismicRichTextProps> = (props) => {
 	const {

src/PrismicTable.tsx

@@ -60,37 +60,15 @@ export type PrismicTableProps = {
 };
 
 /**
- * React component that renders content from a Prismic table field. By default,
- * HTML elements are rendered for each piece of content. A `tbody` block will
- * render a `<tbody>` HTML element, for example.
+ * Renders content from a Prismic table field as React components.
  *
- * To customize the components that are rendered, provide a map serializer to
- * the `components` prop.
+ * @example
  *
- * @example Rendering a table field using the default HTMl elements.
- *
- * ```jsx
- * <PrismicTable field={document.data.my_table} />;
- * ```
- *
- * @example Rendering a table field using a custom set of React components.
- *
- * ```jsx
- * <PrismicTable
- * 	field={document.data.my_table}
- * 	components={{
- * 		tbody: ({ children }) => (
- * 			<tbody className="my-class">{children}</tbody>
- * 		),
- * 	}}
- * />;
+ * ```tsx
+ * <PrismicTable field={slice.primary.pricing_table} />;
  * ```
  *
- * @param props - Props for the component.
- *
- * @returns The table field's content as React components.
- *
- * @see Learn about table fields {@link https://prismic.io/docs/core-concepts/table}
+ * @see Learn how to style tables and customize table element components: {@link https://prismic.io/docs/fields/table}
  */
 export const PrismicTable: FC<PrismicTableProps> = (props) => {
 	const { field, components, fallback = null } = props;

src/PrismicText.tsx

@@ -6,7 +6,7 @@ import { devMsg } from "./lib/devMsg.js";
 
 /** Props for `<PrismicText>`. */
 export type PrismicTextProps = {
-	/** The Prismic Rich Text field to render. */
+	/** The Prismic rich text field to render. */
 	field: RichTextField | null | undefined;
 
 	/**
@@ -20,24 +20,15 @@ export type PrismicTextProps = {
 };
 
 /**
- * React component that renders content from a Prismic Rich Text field as plain
- * text.
+ * Renders content from a Prismic rich text field as plain text (no HTML).
  *
- * @remarks
- * This component returns a React fragment with no wrapping element around the
- * content. If you need a wrapper, add a component around `<PrismicText>`.
+ * @example
  *
- * @example Rendering a Rich Text field as plain text.
- *
- * ```jsx
- * <PrismicText field={document.data.content} />;
+ * ```tsx
+ * <PrismicText field={slice.primary.text} />;
  * ```
  *
- * @param props - Props for the component.
- *
- * @returns The Rich Text field's content as plain text.
- *
- * @see Learn about Rich Text fields {@link https://io/docs/core-concepts/rich-text-title}
+ * @see Learn how to display rich text as plain text or React components: {@link https://prismic.io/docs/fields/rich-text}
  */
 export const PrismicText: FC<PrismicTextProps> = (props) => {
 	const { field, fallback, separator } = props;
@@ -56,7 +47,7 @@ export const PrismicText: FC<PrismicTextProps> = (props) => {
 	if (typeof props.field === "string") {
 		if (DEV) {
 			console.error(
-				`[PrismicText] The "field" prop only accepts a Rich Text or Title field's value but was provided a different type of field instead (e.g. a Key Text or Select field). You can resolve this error by rendering the field value inline without <PrismicText>. For more details, see ${devMsg(
+				`[PrismicText] The "field" prop only accepts a rich text field's value but was provided a different type of field instead (e.g. a key text or select field). You can resolve this error by rendering the field value inline without <PrismicText>. For more details, see ${devMsg(
 					"prismictext-works-only-with-rich-text-and-title-fields",
 				)}`,
 				props.field,

src/PrismicToolbar.tsx

@@ -13,8 +13,15 @@ export type PrismicToolbarProps = {
 };
 
 /**
- * React component that injects the Prismic Toolbar into the app. This component
- * can be placed anywhere in the React tree.
+ * Renders the Prismic Toolbar script to support draft previews.
+ *
+ * @example
+ *
+ * ```tsx
+ * <PrismicToolbar repositoryName="my-repo" />;
+ * ```
+ *
+ * @see Learn how to set up preview functionality and the toolbar's role in preview sessions: {@link https://prismic.io/docs/previews}
  */
 export const PrismicToolbar: FC<PrismicToolbarProps> = (props) => {
 	const { repositoryName } = props;