docs(tsdoc): fixed some tsdoc annotations and styling

This fixed:

- `@return` must be `@returns`
- `@param {name} {description}` must be `@param {name} - {description}`
- `@typeparam {name} {description}` must be `@typeParam {name} - {description}`
- `@default` must be `@defaultValue {value}` (with backticks around value)
- `@private` must be `@internal`
- `>` must be > or in a code block
- inline code blocks must not wrap lines

This partially fixed:

- some cases where I use markdown links instead of `{@link href|name}`

Still remaining:

- change `@since` tag to something else (nothing exists yet)
- fix `Tabs` with how the ids work
- fix generate code about @react-md/dev-utils since it needs to be \@react-md/dev-utils
- fix remaining invalid link usage
- need to verify `@see` usage
  - need to verify `{@link}` usage
  - might be able to use `{@inheritdoc}` for some of these
- updated eslint to use eslint-plugin-tsdoc or upgrade @mlaursen/eslint-config
- fix `Example:` places to be `@example`.
- eventually should update all public exports to be documented correctly

Reference: https://tsdoc.org/

Author: mlaursen

packages/alert/src/MessageQueueContext.tsx

@@ -31,7 +31,7 @@ export interface Message {
    * existing messages will maintain their order but pushed behind this new
    * message.
    *
-   * @default "normal"
+   * @defaultValue `"normal"`
    */
   messagePriority?: MessagePriority;
 
@@ -41,7 +41,7 @@ export interface Message {
    * the user presses the action inside or it is a toast that will be hidden by
    * some other logic (like online/offline).
    *
-   * @default false
+   * @defaultValue `false`
    */
   disableAutohide?: boolean;
 }
@@ -68,7 +68,7 @@ export interface ToastMessage
 export type AddMessage<M extends Message> = (message: M) => void;
 
 /**
- * @private
+ * @internal
  */
 export const AddMessageContext = createContext<AddMessage<Message>>(() => {
   throw new Error(
@@ -77,7 +77,7 @@ export const AddMessageContext = createContext<AddMessage<Message>>(() => {
 });
 
 /**
- * @private
+ * @internal
  */
 export const MessageVisibilityContext = createContext(false);
 
@@ -95,7 +95,7 @@ export function useAddMessage<
 /**
  * Gets the current message visibility to provide to the toast.
  *
- * @private
+ * @internal
  */
 export function useMessageVisibility(): boolean {
   return useContext(MessageVisibilityContext);
@@ -144,7 +144,7 @@ export type RestartVisibilityTimer = () => void;
 export type ResetQueue<M extends Message> = () => M[];
 
 /**
- * @private
+ * @internal
  */
 export interface MessageQueueActions<M extends Message> {
   popMessage: PopMessage;
@@ -156,7 +156,7 @@ export interface MessageQueueActions<M extends Message> {
 }
 
 /**
- * @private
+ * @internal
  */
 export const MessageQueueActionsContext = createContext<
   MessageQueueActions<Message>
@@ -205,7 +205,7 @@ export function useMessageQueueActions<
 }
 
 /**
- * @private
+ * @internal
  */
 export const MessageQueueContext = createContext<Message[]>([]);
 

packages/alert/src/SnackbarQueue.tsx

@@ -47,7 +47,7 @@ function getId(
  * component, it's actually required to create a separate component instance so
  * that the context API can be
  *
- * @private
+ * @internal
  */
 function SnackbarQueueT<M extends ToastMessage = ToastMessage>(
   { queue, onActionClick, ...props }: SnackbarQueueProps<M>,

packages/alert/src/useMessageQueue.ts

@@ -18,7 +18,7 @@ export const POP_MESSAGE = "POP_MESSAGE";
 export const RESET_QUEUE = "RESET_QUEUE";
 
 /**
- * @private
+ * @internal
  */
 export interface AddMessageAction<M extends Message = ToastMessage> {
   type: typeof ADD_MESSAGE;
@@ -27,7 +27,7 @@ export interface AddMessageAction<M extends Message = ToastMessage> {
 }
 
 /**
- * @private
+ * @internal
  */
 export function addMessage<M extends Message = ToastMessage>(
   message: M,
@@ -37,31 +37,31 @@ export function addMessage<M extends Message = ToastMessage>(
 }
 
 /**
- * @private
+ * @internal
  */
 export interface PopMessageAction {
   type: typeof POP_MESSAGE;
 }
 
 /**
- * @private
+ * @internal
  */
 export const popMessage = (): PopMessageAction => ({ type: POP_MESSAGE });
 
 /**
- * @private
+ * @internal
  */
 export interface ResetQueueAction {
   type: typeof RESET_QUEUE;
 }
 
 /**
- * @private
+ * @internal
  */
 export const resetQueue = (): ResetQueueAction => ({ type: RESET_QUEUE });
 
 /**
- * @private
+ * @internal
  */
 export type MessageActions<M extends Message = ToastMessage> =
   | AddMessageAction<M>
@@ -72,7 +72,7 @@ export type MessageActions<M extends Message = ToastMessage> =
  * This function is used to update the message queue state by adding a new message when
  * needed.
  *
- * @private
+ * @internal
  */
 export function handleAddMessage<M extends Message = ToastMessage>(
   state: M[],
@@ -137,7 +137,7 @@ type MessageQueueReducer<M extends Message = ToastMessage> = Reducer<
 >;
 
 /**
- * @private
+ * @internal
  */
 export function reducer<M extends Message = ToastMessage>(
   state: M[],
@@ -174,7 +174,7 @@ export interface MessageQueueResult<M extends Message = ToastMessage>
  * - creating timeouts as needed to show/hide toasts within the SnackbarQueue component
  * - create a way to push messages with optional priority onto the queue
  *
- * @private
+ * @internal
  */
 export function useMessageQueue<M extends Message = ToastMessage>({
   timeout = DEFAULT_MESSAGE_QUEUE_TIMEOUT,

packages/alert/src/useWindowBlurPause.ts

@@ -17,7 +17,7 @@ interface Options {
  * user since they minimized the browser or viewing something on a second
  * screen.
  *
- * @private
+ * @internal
  */
 export function useWindowBlurPause({
   startTimer,

packages/app-bar/src/AppBarTitle.tsx

@@ -58,6 +58,7 @@ export const AppBarTitle = forwardRef<HTMLHeadingElement, AppBarTitleProps>(
   }
 );
 
+/* istanbul ignore next */
 if (process.env.NODE_ENV !== "production") {
   try {
     const PropTypes = require("prop-types");

packages/app-bar/src/useActionClassName.ts

@@ -13,8 +13,8 @@ export interface AppBarActionClassNameProps extends AppBarColorInherit {
 
   /**
    * Boolean if this is the first action within the app bar. This is really just
-   * used to automatically right-align all the actions by applying `margin-left:
-   * auto` to this action.
+   * used to automatically right-align all the actions by applying
+   * `margin-left: auto` to this action.
    */
   first?: boolean;
 
@@ -32,7 +32,7 @@ export interface AppBarActionClassNameProps extends AppBarColorInherit {
  * really not be used externally and is really just for creating dropdown menus
  * within app bars that have the action styles.
  *
- * @private
+ * @internal
  */
 export function useActionClassName({
   first,

packages/app-bar/src/useInheritContext.ts

@@ -2,7 +2,7 @@ import { createContext, useContext } from "react";
 
 /**
  * Boolean if the child components should inherit the color of the app bar.
- * @private
+ * @internal
  */
 export const InheritContext = createContext(false);
 
@@ -21,9 +21,9 @@ export interface AppBarColorInherit {
  * AppBar. If the `inheritColor` prop was provided to the component, that value
  * will be used instead.
  *
- * @param inheritColor The prop inheritColor for the component
- * @return true if the color should be inherited.
- * @private
+ * @param inheritColor - The prop inheritColor for the component
+ * @returns true if the color should be inherited.
+ * @internal
  */
 export function useInheritContext(inheritColor: boolean | undefined): boolean {
   const inheritContext = useContext(InheritContext);
@@ -36,13 +36,13 @@ export function useInheritContext(inheritColor: boolean | undefined): boolean {
  * nested app bars usually happen with prominent toolbars and the root app bar
  * defines the theme.
  *
- * @private
+ * @internal
  */
 export const ParentContext = createContext(false);
 
 /**
  *
- * @private
+ * @internal
  */
 export function useParentContext(): boolean {
   return useContext(ParentContext);

packages/autocomplete/src/useAutoComplete.ts

@@ -91,7 +91,7 @@ export interface AutoCompleteReturnValue {
 /**
  * This hook handles all the autocomplete's "logic" and behavior.
  *
- * @private
+ * @internal
  */
 export function useAutoComplete({
   suggestionsId,

packages/autocomplete/src/utils.ts

@@ -10,9 +10,9 @@ import {
 /**
  * Generates an id for each result in the autocomplete's listbox.
  *
- * @param id The listbox's id
- * @param index The index of the result in the list
- * @return an id string
+ * @param id - The listbox's id
+ * @param index - The index of the result in the list
+ * @returns an id string
  */
 export function getResultId(id: string, index: number): string {
   return `${id}-result-${index + 1}`;
@@ -22,12 +22,12 @@ export function getResultId(id: string, index: number): string {
  * Gets a renderable label for each result in the autocomplete's listbox. This
  * will be applied as the `children` for the `Option` element.
  *
- * @param datum The current result datum to get a label for
- * @param labelKey The key to extract a label from if the datum is an object
- * @param query The current search query. This is useful if you want to
+ * @param datum - The current result datum to get a label for
+ * @param labelKey - The key to extract a label from if the datum is an object
+ * @param query - The current search query. This is useful if you want to
  * implement text "highlighting" (bold) of all the letters that match in the
  * item.
- * @return a renderable node to display
+ * @returns a renderable node to display
  */
 export function getResultLabel(
   datum: Readonly<AutoCompleteData>,
@@ -45,10 +45,10 @@ export function getResultLabel(
 /**
  * Gets a value string from each result that can be searched.
  *
- * @param datum The current result datum that should have a string extracted
- * @param valueKey The key to use to extract a string value from if the datum is
- * an object
- * @return a searchable string.
+ * @param datum - The current result datum that should have a string extracted
+ * @param valueKey - The key to use to extract a string value from if the datum
+ * is an object
+ * @returns a searchable string.
  */
 export function getResultValue(
   datum: Readonly<AutoCompleteData>,
@@ -73,15 +73,15 @@ export function getResultValue(
 /**
  * This is used to disable filtering and just return the data list immediately.
  * Useful when the filtering is done somewhere else like a server/API
- * @private
+ * @internal
  */
 export const noFilter: FilterFunction = (_, data) => data;
 
 /**
  * Gets the filter function to use within the Autocomplete based on the provided
  * filter prop
  *
- * @private
+ * @internal
  */
 export function getFilterFunction<O extends {} = {}>(
   filter: AutoCompleteFilterFunction<O>
@@ -131,7 +131,7 @@ export function getFilterFunction<O extends {} = {}>(
  * }, [])
  * ```
  *
- * @param datum The result data to type guard against.
+ * @param datum - The result data to type guard against.
  */
 export function isResultOf<T extends {}>(
   datum: Readonly<AutoCompleteData>

packages/avatar/src/Avatar.tsx

@@ -27,7 +27,7 @@ export interface AvatarProps extends HTMLAttributes<HTMLSpanElement> {
    * An optional `referrerPolicy` to provide to the `<img>` element if the `src`
    * or `imgProps` props are provided.
    *
-   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-referrerpolicy
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-referrerpolicy|Referrer Policy}
    *
    * @since 2.2.0
    */

packages/badge/src/BadgedButton.tsx

@@ -18,7 +18,7 @@ export interface BadgedButtonProps
 
   /**
    * An optional id for the badge. Either this prop or the `id` prop is required
-   * for a11y when the `badgeChildren` is provided` to create the
+   * for a11y when the `badgeChildren` is provided to create the
    * `aria-describedby` value on the button.
    */
   badgeId?: string;

packages/badge/src/isEmpty.ts

@@ -3,7 +3,7 @@ import { ReactNode } from "react";
 /**
  * A small util to check if the badge is considered empty.
  *
- * @private
+ * @internal
  */
 export function isEmpty(
   children: ReactNode,

packages/button/src/buttonThemeClassNames.ts

@@ -75,9 +75,9 @@ const block = bem("rmd-button");
  * used so that other elements like clickable `<div>`s or `<input type="file">`
  * can look like buttons.
  *
- * @param props An object containing the themeable button props to generate a
+ * @param props - An object containing the themeable button props to generate a
  * button theme className.
- * @return a string of class names to create an element with a button theme.
+ * @returns a string of class names to create an element with a button theme.
  */
 export function buttonThemeClassNames({
   theme: propTheme = "clear",

packages/card/src/CardHeaderAddon.tsx

@@ -9,7 +9,7 @@ const block = bem("rmd-card");
  * This component is used to dynamically add addons to the `CardHeader`
  * component. When no children are provided, nothing will be rendered.
  *
- * @private
+ * @internal
  */
 export function CardHeaderAddon({
   className,

packages/chip/src/Chip.tsx

@@ -70,8 +70,10 @@ export interface ChipProps extends ButtonAttributes {
    * `true` and will transition in and out when swapped between `true` and
    * `false`.
    *
-   * > See the `disableIconTransition` and `selectedIcon` props for more details
-   * > about the icon behavior
+   * @remarks
+   *
+   * See the `disableIconTransition` and `selectedIcon` props for more details
+   * about the icon behavior
    */
   selected?: boolean;