Add documentation to functions

Author: JCQuintas

packages/mui-material/src/styles/useThemeProps.d.ts

@@ -11,6 +11,33 @@ export type ThemedProps<Theme, Name extends keyof any> = Theme extends {
   ? Props
   : {};
 
+/**
+ * Merges input `props` with the `defaultProps` for a component that were defined in the theme.
+ *
+ * The `defaultProps` are defined in the theme under `theme.components[componentName].defaultProps`.
+ *
+ * @example
+ *
+ * ```tsx
+ * const createTheme = () => ({
+ *   components: {
+ *     MuiStat: {
+ *       defaultProps: {
+ *         variant: 'outlined',
+ *       },
+ *     },
+ *   },
+ * });
+ *
+ * function Stat(props) {
+ *   const themeProps = useThemeProps({ props, name: 'MuiStat' });
+ *   return <div {...themeProps} />;
+ * }
+ * ```
+ *
+ * @param params.props The input props
+ * @param params.name The name of the component as defined in the theme
+ */
 export default function useThemeProps<
   Theme extends ThemeWithProps,
   Props,

packages/mui-utils/src/composeClasses/composeClasses.ts

@@ -3,6 +3,34 @@
    These rules are preventing the performance optimizations below.
  */
 
+/**
+ * Compose classes from multiple sources.
+ *
+ * @example
+ * ```tsx
+ * const slots = {
+ *  root: ['root', 'primary'],
+ *  label: ['label'],
+ * };
+ *
+ * const getUtilityClass = (slot) => `MuiButton-${slot}`;
+ *
+ * const classes = {
+ *   root: 'my-root-class',
+ * };
+ *
+ * const output = composeClasses(slots, getUtilityClass, classes);
+ * // {
+ * //   root: 'MuiButton-root MuiButton-primary my-root-class',
+ * //   label: 'MuiButton-label',
+ * // }
+ * ```
+ *
+ * @param slots a list of classes for each possible slot
+ * @param getUtilityClass a function to resolve the class based on the slot name
+ * @param classes the input classes from props
+ * @returns the resolved classes for all slots
+ */
 export default function composeClasses<ClassKey extends string>(
   slots: Record<ClassKey, ReadonlyArray<string | false | undefined | null>>,
   getUtilityClass: (slot: string) => string,

packages/mui-utils/src/deepmerge/deepmerge.test.ts

@@ -131,4 +131,10 @@ describe('deepmerge', () => {
 
     expect(result.element).to.equal(element2);
   });
+
+  it('should deep clone example correctly', () => {
+    const result = deepmerge({ a: { b: 1 }, d: 2 }, { a: { c: 2 }, d: 4 });
+
+    expect(result).to.deep.equal({ a: { b: 1, c: 2 }, d: 4 });
+  });
 });

packages/mui-utils/src/deepmerge/deepmerge.ts

@@ -34,6 +34,24 @@ function deepClone<T>(source: T): T | Record<keyof any, unknown> {
   return output;
 }
 
+/**
+ * Merge objects deeply.
+ * It will shallow copy React elements.
+ *
+ * If `options.clone` is set to `false` the source object will be merged directly into the target object.
+ *
+ * @example
+ * ```ts
+ * deepmerge({ a: { b: 1 }, d: 2 }, { a: { c: 2 }, d: 4 });
+ * // => { a: { b: 1, c: 2 }, d: 4 }
+ * ````
+ *
+ * @param target The target object.
+ * @param source The source object.
+ * @param options The merge options.
+ * @param options.clone Set to `false` to merge the source object directly into the target object.
+ * @returns The merged object.
+ */
 export default function deepmerge<T>(
   target: T,
   source: unknown,