chore(docs): clean up miscellaneous component documentation

CHANGELOG.md

@@ -21,6 +21,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - Fix `bodyBackground` color for Teams dark theme to be the correct grey value @codepretty ([#1961](https://github.com/stardust-ui/react/pull/1961))
 - Updating `Button` styles for Teams dark & high contrast themes to match design @notandrew ([#1933](https://github.com/stardust-ui/react/pull/1933))
 - Update Office brand icons in Teams theme with latest version @notandrew ([#1954](https://github.com/stardust-ui/react/pull/1954))
+- Fix various component documentation issues @davezuko ([#1992](https://github.com/stardust-ui/react/pull/1992))
 
 ### Features
 - Add experimental runtime accessibility attributes validation (the initial step validates the Button component only) @mshoho ([#1911](https://github.com/stardust-ui/react/pull/1911))
@@ -75,7 +76,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 [Compare changes](https://github.com/stardust-ui/react/compare/v0.38.0...v0.38.1)
 
 ### Fixes
-- Fix order of applying unhandled props and key handlers @jurokapsiar ([#1901](https://github.com/stardust-ui/react/pull/1901)) 
+- Fix order of applying unhandled props and key handlers @jurokapsiar ([#1901](https://github.com/stardust-ui/react/pull/1901))
 - Fix handling of `onMouseEnter` prop in `ChatMessage` @layershifter ([#1903](https://github.com/stardust-ui/react/pull/1903))
 - Fix focus styles for `TreeItem` and `HierarchicalTreeItem` @silviuavram ([#1912](https://github.com/stardust-ui/react/pull/1912))
 - Use more accurate positioning for `actions` in `Chat.Message` when is inside scrollable containers @layershifter ([#1929](https://github.com/stardust-ui/react/pull/1929))

packages/react/src/components/Accordion/Accordion.tsx

@@ -37,7 +37,7 @@ export interface AccordionProps extends UIComponentProps, ChildrenComponentProps
   /** Initial activeIndex value. */
   defaultActiveIndex?: number[] | number
 
-  /** Only allow one panel open at a time. */
+  /** Only allow one panel to be expanded at a time. */
   exclusive?: boolean
 
   /** At least one panel should be expanded at any time. */

packages/react/src/components/Alert/Alert.tsx

@@ -45,7 +45,7 @@ export interface AlertProps
    */
   accessibility?: Accessibility
 
-  /** An Alert can contain action buttons. */
+  /** An alert can contain action buttons. */
   actions?: ShorthandValue<ButtonGroupProps> | ShorthandCollection<ButtonProps>
 
   /** An alert may contain an icon. */
@@ -54,7 +54,7 @@ export interface AlertProps
   /** An alert may contain a header. */
   header?: ShorthandValue<TextProps>
 
-  /** Controls Alert's relation to neighboring items. */
+  /** An alert's position relative to neighboring items. */
   attached?: boolean | 'top' | 'bottom'
 
   /** An alert can only take up the width of its content. */
@@ -86,22 +86,22 @@ export interface AlertProps
   onDismiss?: ComponentEventHandler<AlertProps>
 
   /**
-   * Called after user's focus.
+   * Called after the alert is focused.
    * @param {SyntheticEvent} event - React's original SyntheticEvent.
    * @param {object} data - All props.
    */
   onFocus?: ComponentEventHandler<AlertProps>
 
-  /** An alert may be formatted to display a successful message. */
+  /** An alert can be formatted to display a successful message. */
   success?: boolean
 
   /** An alert can be set to visible to force itself to be shown. */
   visible?: boolean
 
-  /** An alert may be formatted to display a warning message. */
+  /** An alert can be formatted to display a warning message. */
   warning?: boolean
 
-  /** Body contains header and content elements. */
+  /** An alert can have a body that contains header and content elements. */
   body?: ShorthandValue<BoxProps>
 }
 
@@ -256,7 +256,7 @@ class Alert extends AutoControlledComponent<WithAsProp<AlertProps>, AlertState>
 }
 
 /**
- * An Alert displays a brief, important message to attract the user's attention without interrupting the user's task.
+ * An Alert displays a brief, important message to attract a user's attention without interrupting their current task.
  *
  * @accessibility
  * Implements [ARIA Alert](https://www.w3.org/TR/wai-aria-practices-1.1/#alert) design pattern.

packages/react/src/components/Animation/Animation.tsx

@@ -24,42 +24,42 @@ export interface AnimationProps
   /** The name for the animation that should be applied, defined in the theme. */
   name?: string
 
-  /** The delay property specifies a delay for the start of an animation. Negative values are
+  /** Specifies a delay for the start of an animation. Negative values are
    * also allowed. If using negative values, the animation will start as if it had already been
-   * playing for N seconds.
+   * playing for that amount of time.
    */
   delay?: string
 
-  /** The direction property specifies whether an animation should be played forwards, backwards
-   * or in alternate cycles. It can have the following values:
-   * - normal - The animation is played as normal (forwards). This is default
+  /** Specifies whether an animation should be played forwards, backwards or in alternate cycles.
+   * It can have the following values:
+   * - normal (default) - The animation is played as normal (forwards)
    * - reverse - The animation is played in reverse direction (backwards)
    * - alternate - The animation is played forwards first, then backwards
-   * - alternate-reverse - The animation is played backwards first, then forwards.
+   * - alternate-reverse - The animation is played backwards first, then forwards
    */
   direction?: string
 
-  /** The duration property defines how long time an animation should take to complete. */
+  /** Specifies how long an animation should take to complete. */
   duration?: string
 
   /**
-   * The fillMode property specifies a style for the target element when the animation
-   * is not playing (before it starts, after it ends, or both). It can have the following values:
-   * - none - Default value. Animation will not apply any styles to the element before or after it is executing
+   * Specifies a style for the target element when the animation is not playing (i.e. before it starts, after it ends, or both).
+   * It can have the following values:
+   * - none (default) - Animation will not apply any styles to the element before or after it is executing
    * - forwards - The element will retain the style values that is set by the last keyframe (depends on animation-direction and animation-iteration-count)
    * - backwards - The element will get the style values that is set by the first keyframe (depends on animation-direction), and retain this during the animation-delay period
    * - both - The animation will follow the rules for both forwards and backwards, extending the animation properties in both directions
    * */
   fillMode?: string
 
-  /** The animation-iteration-count property specifies the number of times an animation should run. */
+  /** Specifies the number of times an animation should run. */
   iterationCount?: string
 
   /** Custom parameters for the keyframe defined for the animation. */
   keyframeParams?: object
 
   /**
-   * The playState property specifies whether the animation is running or paused. It can have the following values:
+   * Specifies whether the animation is running or paused. It can have the following values:
    * - paused - Specifies that the animation is paused
    * - running - Default value. Specifies that the animation is running
    * - initial - Sets this property to its default value.
@@ -68,7 +68,7 @@ export interface AnimationProps
   playState?: string
 
   /**
-   * The timingFunction property specifies the speed curve of the animation. It can have the following values:
+   * Specifies the speed curve of the animation. It can have the following values:
    * - ease - Specifies an animation with a slow start, then fast, then end slowly (this is default)
    * - linear - Specifies an animation with the same speed from start to end
    * - ease-in - Specifies an animation with a slow start

packages/react/src/components/Attachment/Attachment.tsx

@@ -30,7 +30,7 @@ export interface AttachmentProps extends UIComponentProps, ChildrenComponentProp
   /** A string describing the attachment. */
   description?: ShorthandValue<TextProps>
 
-  /** An attachment can show it is currently unable to be interacted with. */
+  /** An attachment can show that it cannot be interacted with. */
   disabled?: boolean
 
   /** The name of the attachment. */

packages/react/src/components/Avatar/Avatar.tsx

@@ -36,7 +36,7 @@ export interface AvatarProps extends UIComponentProps {
   /** Shorthand for the status of the user. */
   status?: ShorthandValue<StatusProps>
 
-  /** Custom method for generating the initials from the name property, shown in the avatar if there is no image provided. */
+  /** Custom method for generating the initials from the name property, which is shown if no image is provided. */
   getInitials?: (name: string) => string
 }
 
@@ -125,6 +125,6 @@ class Avatar extends UIComponent<WithAsProp<AvatarProps>, any> {
 Avatar.create = createShorthandFactory({ Component: Avatar, mappedProp: 'name' })
 
 /**
- * An Avatar is a graphic representation of a user.
+ * An Avatar is a graphical representation of a user.
  */
 export default withSafeTypeForAs<typeof Avatar, AvatarProps>(Avatar)

packages/react/src/components/Button/Button.tsx

@@ -33,51 +33,51 @@ export interface ButtonProps
   /** A button can appear circular. */
   circular?: boolean
 
-  /** A button can show it is currently unable to be interacted with. */
+  /** A button can show that it cannot be interacted with. */
   disabled?: boolean
 
-  /** A button can take the width of its container. */
+  /** A button can fill the width of its container. */
   fluid?: boolean
 
-  /** Button can have an icon. */
+  /** A button can have an icon. */
   icon?: ShorthandValue<IconProps>
 
-  /** A button may indicate that it has only icon. */
+  /** A button can contain only an icon. */
   iconOnly?: boolean
 
-  /** An icon button can format an Icon to appear before or after the button */
+  /** An icon button can format its Icon to appear before or after its content */
   iconPosition?: 'before' | 'after'
 
-  /** A button in loading state, can show a loader. */
+  /** Shorthand to customize a button's loader. */
   loader?: ShorthandValue<LoaderProps>
 
   /** A button can show a loading indicator. */
   loading?: boolean
 
   /**
-   * Called after user's click.
+   * Called after a user clicks the button.
    * @param {SyntheticEvent} event - React's original SyntheticEvent.
    * @param {object} data - All props.
    */
   onClick?: ComponentEventHandler<ButtonProps>
 
   /**
-   * Called after user's focus.
+   * Called after a user focuses the button.
    * @param {SyntheticEvent} event - React's original SyntheticEvent.
    * @param {object} data - All props.
    */
   onFocus?: ComponentEventHandler<ButtonProps>
 
-  /** A button can be formatted to show different levels of emphasis. */
+  /** A button can emphasize that it represents the primary action. */
   primary?: boolean
 
-  /** A button can be formatted to show only text in order to indicate some less-pronounced actions. */
+  /** A button can be formatted to show only text in order to indicate a less-pronounced action. */
   text?: boolean
 
-  /** A button can be formatted to show different levels of emphasis. */
+  /** A button can emphasize that it represents an alternative action. */
   secondary?: boolean
 
-  /** A size of the button. */
+  /** A button can be sized. */
   size?: SizeValue
 }
 
@@ -198,7 +198,7 @@ class Button extends UIComponent<WithAsProp<ButtonProps>> {
 Button.create = createShorthandFactory({ Component: Button, mappedProp: 'content' })
 
 /**
- * A Button enables users to trigger an event or take an action, such as submitting a form, opening a dialog, etc.
+ * A Button enables users to take an action, such as submitting a form, opening a dialog, etc.
  *
  * @accessibility
  * Implements [ARIA Button](https://www.w3.org/TR/wai-aria-practices-1.1/#button) design pattern.

packages/react/src/components/Chat/Chat.tsx

@@ -74,6 +74,6 @@ class Chat extends UIComponent<WithAsProp<ChatProps>, any> {
 }
 
 /**
- * A Chat displays conversation messages between users.
+ * A Chat displays messages from a conversation between multiple users.
  */
 export default withSafeTypeForAs<typeof Chat, ChatProps, 'ul'>(Chat)

packages/react/src/components/Checkbox/Checkbox.tsx

@@ -27,39 +27,39 @@ export interface CheckboxProps extends UIComponentProps, ChildrenComponentProps
   /** Accessibility behavior if overridden by the user. */
   accessibility?: Accessibility
 
-  /** Initial checked value. */
+  /** A checkbox can be checked by default. */
   defaultChecked?: SupportedIntrinsicInputProps['defaultChecked']
 
-  /** Whether or not item is checked. */
+  /** A checkbox's checked state can be controlled. */
   checked?: SupportedIntrinsicInputProps['checked']
 
-  /** An item can appear disabled and be unable to change states. */
+  /** A checkbox can appear disabled and be unable to change states. */
   disabled?: SupportedIntrinsicInputProps['disabled']
 
-  /** The item indicator can be user-defined icon. */
+  /** A checkbox's indicator icon can be customized. */
   icon?: ShorthandValue<IconProps>
 
-  /** The label of the item. */
+  /** A checkbox can render a label next to its indicator. */
   label?: ShorthandValue<TextProps>
 
-  /** A label in the loader can have different positions. */
+  /** A checkbox's label can be rendered in different positions. */
   labelPosition?: 'start' | 'end'
 
   /**
-   * Called after item checked state is changed.
+   * Called after a checkbox's checked state is changed.
    * @param {SyntheticEvent} event - React's original SyntheticEvent.
    * @param {object} data - All props.
    */
   onChange?: ComponentEventHandler<CheckboxProps>
 
   /**
-   * Called after click.
+   * Called after a checkbox is clicked.
    * @param {SyntheticEvent} event - React's original SyntheticEvent.
    * @param {object} data - All props.
    */
   onClick?: ComponentEventHandler<CheckboxProps>
 
-  /** A checkbox can be formatted to show an on or off choice. */
+  /** A checkbox can be formatted to show an "on or off" choice. */
   toggle?: boolean
 }
 
@@ -185,7 +185,7 @@ Checkbox.create = createShorthandFactory({
 })
 
 /**
- * A Checkbox allows to toggle between two choices -- checked and not checked.
+ * A Checkbox allows a user to make a choice between two mutually exclusive options.
  *
  * @accessibility
  * Implements [ARIA Checkbox](https://www.w3.org/TR/wai-aria-practices-1.1/#checkbox) design pattern.

packages/react/src/components/Dialog/Dialog.tsx

@@ -48,13 +48,13 @@ export interface DialogProps
   /** A dialog can contain a cancel button. */
   cancelButton?: ShorthandValue<ButtonProps>
 
-  /** Controls whether or not a dialog should close when a click outside is happened. */
+  /** A dialog can be closed when a user clicks outside of it. */
   closeOnOutsideClick?: boolean
 
   /** A dialog can contain a confirm button. */
   confirmButton?: ShorthandValue<ButtonProps>
 
-  /** Initial value for 'open'. */
+  /** A dialog can be open by default. */
   defaultOpen?: boolean
 
   /** A dialog can contain a header. */
@@ -64,27 +64,27 @@ export interface DialogProps
   headerAction?: ShorthandValue<ButtonProps>
 
   /**
-   * Called after user's click a cancel button.
+   * Called after a user clicks the cancel button.
    * @param {SyntheticEvent} event - React's original SyntheticEvent.
    * @param {object} data - All props.
    */
   onCancel?: ComponentEventHandler<DialogProps>
 
   /**
-   * Called after user's click a confirm button.
+   * Called after a user clicks the confirm button.
    * @param {SyntheticEvent} event - React's original SyntheticEvent.
    * @param {object} data - All props.
    */
   onConfirm?: ComponentEventHandler<DialogProps>
 
   /**
-   * Called after user's opened a dialog.
+   * Called after a user opens the dialog.
    * @param {SyntheticEvent} event - React's original SyntheticEvent.
    * @param {object} data - All props.
    */
   onOpen?: ComponentEventHandler<DialogProps>
 
-  /** Defines whether a dialog is displayed. */
+  /** A dialog's open state can be controlled. */
   open?: boolean
 
   /** A dialog can contain a overlay. */
@@ -372,7 +372,7 @@ Dialog.slotClassNames = {
 }
 
 /**
- * A Dialog displays important information on top of a page which usually requires user's attention, confirmation or interaction.
+ * A Dialog displays important information on top of a page which requires a user's attention, confirmation, or interaction.
  * Dialogs are purposefully interruptive, so they should be used sparingly.
  *
  * @accessibility

packages/react/src/components/Divider/Divider.tsx

@@ -27,13 +27,13 @@ export interface DividerProps
    */
   accessibility?: Accessibility
 
-  /** A divider can be fitted, without any space above or below it.  */
+  /** A divider can be fitted, without any space above or below it. */
   fitted?: boolean
 
-  /** Size multiplier (default 0) * */
+  /** A divider can be resized using this multiplier. (default: 0) */
   size?: number
 
-  /** A divider can appear more important and draw the user's attention. */
+  /** A divider can be emphasized to draw a user's attention. */
   important?: boolean
 }
 
@@ -74,6 +74,6 @@ class Divider extends UIComponent<WithAsProp<DividerProps>, any> {
 Divider.create = createShorthandFactory({ Component: Divider, mappedProp: 'content' })
 
 /**
- * A Divider visually segments content into groups.
+ * A Divider visually segments content.
  */
 export default withSafeTypeForAs<typeof Divider, DividerProps>(Divider)