Improve and fixup documentation

packages/components/src/base-control/index.js

@@ -10,12 +10,18 @@ import VisuallyHidden from '../visually-hidden';
 
 /**
  * @typedef Props
- * @property {string} id ID
- * @property {import('react').ReactNode} help Help text
- * @property {import('react').ReactNode} label Help text
- * @property {boolean} [hideLabelFromVision] True to visually hide the label
- * @property {string} [className] Class name
- * @property {import('react').ReactNode} [children] Children
+ * @property {string} id The id of the element to which labels and help text are being generated.
+ *                       That element should be passed as a child.
+ * @property {import('react').ReactNode} help If this property is added, a help text will be
+ *                                            generated using help property as the content.
+ * @property {import('react').ReactNode} label If this property is added, a label will be generated
+ *                                             using label property as the content.
+ * @property {boolean} [hideLabelFromVision] If true, the label will only be visible to screen readers.
+ * @property {string} [className] The class that will be added with "components-base-control" to the
+ *                                classes of the wrapper div. If no className is passed only
+ *                                components-base-control is used.
+ * @property {import('react').ReactNode} [children] The content to be displayed within
+ *                                                  the BaseControl.
  */
 
 /**

packages/components/src/visually-hidden/index.js

@@ -10,8 +10,13 @@ import { renderAsRenderProps } from './utils';
 
 /**
  * @template {keyof JSX.IntrinsicElements | import('react').JSXElementConstructor<any>} T
- * @typedef Props
- * @property {T} [as='div'] Component to render
+ * @typedef OwnProps
+ * @property {T} [as='div'] Component to render, e.g. `"div"` or `MyComponent`.
+ */
+
+/**
+ * @template {keyof JSX.IntrinsicElements | import('react').JSXElementConstructor<any>} T
+ * @typedef {OwnProps<T> & import('react').ComponentProps<T>} Props
  */
 
 /**
@@ -20,7 +25,7 @@ import { renderAsRenderProps } from './utils';
  *
  * @template {keyof JSX.IntrinsicElements | import('react').JSXElementConstructor<any>} T
  *
- * @param {Props<T> & import('react').ComponentProps<T>} props  A tag or component to render.
+ * @param {Props<T>} props
  * @return {JSX.Element} Element
  */
 function VisuallyHidden( { as = 'div', className, ...props } ) {
@@ -30,5 +35,4 @@ function VisuallyHidden( { as = 'div', className, ...props } ) {
 		...props,
 	} );
 }
-
 export default VisuallyHidden;

packages/components/src/visually-hidden/utils.js

@@ -1,10 +1,15 @@
 /**
  * @template {keyof JSX.IntrinsicElements | import('react').JSXElementConstructor<any>} T
- * @typedef Props
- * @property {T} [as='div'] Element to render
+ * @typedef OwnProps
+ * @property {T} [as='div'] Component to render
  * @property {import('react').ReactNode | ((props: import('react').ComponentProps<T>) => JSX.Element) } [children] Children or render props function
  */
 
+/**
+ * @template {keyof JSX.IntrinsicElements | import('react').JSXElementConstructor<any>} T
+ * @typedef {OwnProps<T> & import('react').ComponentProps<T>} Props
+ */
+
 /**
  * renderAsRenderProps is used to wrap a component and convert
  * the passed property "as" either a string or component, to the
@@ -13,8 +18,8 @@
  * See VisuallyHidden hidden for example.
  *
  * @template {keyof JSX.IntrinsicElements | import('react').JSXElementConstructor<any>} T
- * @param {Props<T> & import('react').ComponentProps<T>} props A tag or component to render.
- * @return {JSX.Element} The rendered component.
+ * @param {Props<T>} props
+ * @return {JSX.Element} The rendered element.
  */
 function renderAsRenderProps( { as: Component = 'div', ...props } ) {
 	if ( typeof props.children === 'function' ) {