add comment for the new hooks

packages/ra-core/src/controller/field/useReferenceMany.ts

@@ -10,9 +10,9 @@ import {
     getTotal,
     nameRelatedTo,
 } from '../../reducer/admin/references/oneToMany';
-import { Record, Sort, RecordMap, Identifier, Dispatch } from '../../types';
+import { Record, Sort, RecordMap, Identifier } from '../../types';
 
-interface ChildrenFuncParams {
+interface ReferenceManyProps {
     data: RecordMap;
     ids: Identifier[];
     loadedOnce: boolean;
@@ -39,6 +39,50 @@ interface Options {
 
 const defaultFilter = {};
 
+/**
+ * @typedef ReferenceManyProps
+ * @type {Object}
+ * @property {Object} data: the referenced records dictionary by their ids.
+ * @property {Object} ids: the list of referenced records ids.
+ * @property {boolean} loadedOnce: boolean indicating if the references has already be loaded loaded
+ * @property {string | false} referenceBasePath base path of the related record
+ */
+
+/**
+ * Fetch reference records, and return them when avaliable
+ *
+ * The reference prop sould be the name of one of the <Resource> components
+ * added as <Admin> child.
+ *
+ * @example
+ *
+ * const { isLoading, referenceRecord, resourceLinkPath } = useReferenceMany({
+ *     resource
+ *     reference: 'users',
+ *     record: {
+ *         userId: 7
+ *     }
+ *     target: 'comments',
+ *     source: 'userId',
+ *     basePath: '/comments',
+ *     page: 1,
+ *     perPage: 25,
+ * });
+ *
+ * @param {Object} option
+ * @param {string} option.resource The current resource name
+ * @param {string} option.reference The linked resource name
+ * @param {Object} option.record The current resource record
+ * @param {string} option.target The target resource key
+ * @param {Object} option.filter The filter applied on the recorded records list
+ * @param {string} option.source The key of the linked resource identifier
+ * @param {string} option.basePath basepath to current resource
+ * @param {number} option.page the page number
+ * @param {number} option.perPage the number of item per page
+ * @param {object} option.sort the sort to apply to the referenced records
+ *
+ * @returns {ReferenceManyProps} The reference many props
+ */
 const useReferenceMany = ({
     resource,
     reference,
@@ -50,7 +94,7 @@ const useReferenceMany = ({
     page,
     perPage,
     sort = { field: 'id', order: 'DESC' },
-}: Options): ChildrenFuncParams => {
+}: Options): ReferenceManyProps => {
     const referenceId = get(record, source);
     const relatedTo = useMemo(
         () => nameRelatedTo(reference, referenceId, resource, target, filter),
@@ -69,14 +113,14 @@ const useReferenceMany = ({
         fetchReferences({
             reference,
             referenceId,
-            resource,
             target,
             filter,
             source,
             page,
             perPage,
             sort,
             dispatch,
+            relatedTo,
         }),
         [
             reference,
@@ -107,23 +151,15 @@ const useReferenceMany = ({
 const fetchReferences = ({
     reference,
     referenceId,
-    resource,
     target,
     filter,
     source,
     dispatch,
     page,
     perPage,
     sort,
+    relatedTo,
 }) => () => {
-    const relatedTo = nameRelatedTo(
-        reference,
-        referenceId,
-        resource,
-        target,
-        filter
-    );
-
     dispatch(
         crudGetManyReference(
             reference,

packages/ra-core/src/controller/usePagination.ts

@@ -7,6 +7,32 @@ interface PaginationProps {
     setPerPage: (perPage: number) => void;
 }
 
+/**
+ * set the sort to the given field, swap the order if the field is the same
+ * @name setNumber
+ * @function
+ * @param {number} state the state value
+ */
+
+/**
+ * @typedef PaginationProps
+ * @type {Object}
+ * @property {number} page: The page number.
+ * @property {number} perPage: The number of item per page.
+ * @property {setNumber} setPage: Set the page number
+ * @property {setNumber} setPerPage: Set the per page number
+ */
+
+/**
+ * Hooks to provide pagination state (apge and perPage)
+ *
+ * @example
+ *
+ * const { page, setpage, perPage, setPerPage } = usePagination(initialPerPage);
+ *
+ * @param {numper} initialPerPage the initial value per page
+ * @returns {PaginationProps} The pagination props
+ */
 export default (initialPerPage: number = 25): PaginationProps => {
     const [page, setPage] = useState(1);
     const [perPage, setPerPage] = useState(initialPerPage);

packages/ra-core/src/controller/useSort.ts

@@ -22,6 +22,34 @@ const sortReducer = (state: Sort, field: string | Sort): Sort => {
     return { field, order };
 };
 
+/**
+ * set the sort to the given field, swap the order if the field is the same
+ * @name setSort
+ * @function
+ * @param {string} field the name of the field to sort
+ */
+
+/**
+ * @typedef SortProps
+ * @type {Object}
+ * @property {Object} sort: the sort object.
+ * @property {String} sort.field: the sort object.
+ * @property {'ASC' | 'DESC'} sort.order: the sort object.
+ * @property {setSort} setSort
+ */
+
+/**
+ * Hooks to provide sort state
+ *
+ * @example
+ *
+ * const { sort, setSort } = useSort({ field: 'name',order: 'ASC' });
+ *
+ * @param {Object} initialSort
+ * @param {string} initialSort.resource The current resource name
+ * @param {string} initialSort.reference The linked resource name
+ * @returns {SortProps} The sort props
+ */
 export default (
     initialSort: Sort = { field: 'id', order: 'DESC' }
 ): SortProps => {