From 3d1635f764c5627b1100bf9fa4928da436bf823a Mon Sep 17 00:00:00 2001
From: sebashwa <sebastian@priorist.com>
Date: Thu, 16 Nov 2023 23:45:43 +0100
Subject: [PATCH 1/6] Add props headings for some components

---
 docs/Create.md               | 2 ++
 docs/CreateBase.md           | 2 ++
 docs/CreateDialog.md         | 2 ++
 docs/CreateInDialogButton.md | 2 ++
 docs/Edit.md                 | 2 ++
 docs/EditBase.md             | 2 ++
 docs/EditDialog.md           | 4 +++-
 docs/SaveButton.md           | 2 ++
 docs/Toolbar.md              | 2 ++
 9 files changed, 19 insertions(+), 1 deletion(-)

diff --git a/docs/Create.md b/docs/Create.md
index 6190ab2cdd9..4b0f91acd67 100644
--- a/docs/Create.md
+++ b/docs/Create.md
@@ -50,6 +50,8 @@ const App = () => (
 export default App;
 ```
 
+## Props
+
 You can customize the `<Create>` component using the following props:
 
 * [`actions`](#actions): override the actions toolbar with a custom component
diff --git a/docs/CreateBase.md b/docs/CreateBase.md
index 73e9d1ce7f5..efc0afe6391 100644
--- a/docs/CreateBase.md
+++ b/docs/CreateBase.md
@@ -38,6 +38,8 @@ export const BookCreate = () => (
 );
 ```
 
+## Props
+
 You can customize the `<CreateBase>` component using the following props, documented in the `<Create>` component:
 
 * `children`: the components that renders the form
diff --git a/docs/CreateDialog.md b/docs/CreateDialog.md
index eb92cc880e6..324659d7cbb 100644
--- a/docs/CreateDialog.md
+++ b/docs/CreateDialog.md
@@ -57,6 +57,8 @@ In the related `<Resource>`, you don't need to declare a `create` component as t
 
 **Note**: You can't use the `<CreateDialog>` and have a standard `<Edit>` specified on your `<Resource>`, because the `<Routes>` declarations would conflict. If you need this, use the [`<CreateInDialogButton>`](./CreateInDialogButton.md) instead.
 
+## Props
+
 `<CreateDialog>` accepts the same props as the [`<Create>`](./Create.md) component, and the same type of children (e.g. a [`<SimpleForm>`](./SimpleForm.md) element).
 
 * `children`: the components that renders the form
diff --git a/docs/CreateInDialogButton.md b/docs/CreateInDialogButton.md
index b5dd02e3320..c7809ab29e4 100644
--- a/docs/CreateInDialogButton.md
+++ b/docs/CreateInDialogButton.md
@@ -63,6 +63,8 @@ const CompanyShow = () => (
 
 In the above example, `<CreateInDialogButton>` is used to create a new employee for the current company. [The `<WithRecord>` component](./WithRecord.md) helps to set the new employee company id by default.
 
+## Props
+
 `<CreateInDialogButton>` accepts the following props:
 
 * `inline`: set to true to display only a Material UI `<IconButton>` instead of the full `<Button>`. The label will still be available as a `<Tooltip>` though.
diff --git a/docs/Edit.md b/docs/Edit.md
index 3a12eaf1f51..c97db270183 100644
--- a/docs/Edit.md
+++ b/docs/Edit.md
@@ -58,6 +58,8 @@ const App = () => (
 export default App;
 ```
 
+## Props
+
 You can customize the `<Edit>` component using the following props:
 
 * [`actions`](#actions): override the actions toolbar with a custom component
diff --git a/docs/EditBase.md b/docs/EditBase.md
index 33c39947ce5..49b92ee732b 100644
--- a/docs/EditBase.md
+++ b/docs/EditBase.md
@@ -38,6 +38,8 @@ export const BookEdit = () => (
 );
 ```
 
+## Props
+
 You can customize the `<EditBase>` component using the following props, documented in the `<Edit>` component:
 
 * `children`: the components that renders the form
diff --git a/docs/EditDialog.md b/docs/EditDialog.md
index 4d58dee2c13..515e37ad276 100644
--- a/docs/EditDialog.md
+++ b/docs/EditDialog.md
@@ -54,6 +54,8 @@ In the related `<Resource>`, you don't need to declare an `edit` component as th
 <Resource name="customers" list={CustomerList} />
 ```
 
+## Props
+
 `<EditDialog>` accepts the same props as the [`<Edit>`](./Edit.md) component, and the same type of children (e.g. a [`<SimpleForm>`](./SimpleForm.md) element).
 
 * `children`: the components that renders the form
@@ -123,4 +125,4 @@ const CompanyShow = () => (
 );
 ```
 
-Check [the `<EditInDialogButton>` component](./EditInDialogButton.md) for more details.
\ No newline at end of file
+Check [the `<EditInDialogButton>` component](./EditInDialogButton.md) for more details.
diff --git a/docs/SaveButton.md b/docs/SaveButton.md
index 8796fa09335..2239d647a07 100644
--- a/docs/SaveButton.md
+++ b/docs/SaveButton.md
@@ -46,6 +46,8 @@ const PostEdit = () => (
 );
 ```
 
+## Props
+
 `<SaveButton>` accepts the following props:
 
 - [`icon`](#icon)
diff --git a/docs/Toolbar.md b/docs/Toolbar.md
index 9a0a5f1352a..8160931fb37 100644
--- a/docs/Toolbar.md
+++ b/docs/Toolbar.md
@@ -40,6 +40,8 @@ const CommentCreate = () => (
 );
 ```
 
+## Props
+
 `<Toolbar>` accepts the following props:
 
 - [`children`](#children)

From a3f9567bceb405a033e56d5ff0969a75104f949d Mon Sep 17 00:00:00 2001
From: sebashwa <sebastian@priorist.com>
Date: Thu, 16 Nov 2023 23:46:13 +0100
Subject: [PATCH 2/6] Use more consistent documentation style for hooks

---
 docs/useCreateContext.md              |  16 ++--
 docs/useCreateController.md           |  34 ++++----
 docs/useEditContext.md                |  30 +++----
 docs/useEditController.md             |  50 ++++++------
 docs/useList.md                       |  82 ++++++++++---------
 docs/useListContext.md                |  77 +++++++++---------
 docs/useListController.md             | 109 ++++++++++++++------------
 docs/useRegisterMutationMiddleware.md |   4 +-
 docs/useSaveContext.md                |  14 ++--
 docs/useShowContext.md                |  25 +++---
 docs/useShowController.md             |  36 +++++----
 docs/useUnique.md                     |  18 +++--
 12 files changed, 262 insertions(+), 233 deletions(-)

diff --git a/docs/useCreateContext.md b/docs/useCreateContext.md
index ab720e5b6bc..8e02439376a 100644
--- a/docs/useCreateContext.md
+++ b/docs/useCreateContext.md
@@ -40,14 +40,10 @@ const PostCreateForm = () => {
 
 ## Return Value
 
-The `useCreateContext` hook returns an object with the same keys as returned by [`useCreateController`](./useCreateController.md):
+`useCreateContext` returns an object with the same keys as [`useCreateController`](./useCreateController.md):
 
-```jsx
-const {
-    defaultTitle, // the translated title based on the resource, e.g. 'Create New Post'
-    redirect, // the default redirection route. Defaults to 'list'
-    resource, // the resource name, deduced from the location. e.g. 'posts'
-    save, // the update callback, to be passed to the underlying form as submit handler
-    saving, // boolean that becomes true when the dataProvider is called to create the record
-} = useCreateContext();
-```
+* `defaultTitle`: Translated title based on the resource, e.g. 'Create New Post'
+* `redirect`: Default redirect route. Defaults to 'list'
+* `resource`: Resource name, deduced from the location. e.g. 'posts'
+* `save`: Update callback to be passed to the underlying form as submit handler
+* `saving`: Boolean, `true` when the dataProvider is called to create the record
diff --git a/docs/useCreateController.md b/docs/useCreateController.md
index eaca03499ce..d1cf98469ab 100644
--- a/docs/useCreateController.md
+++ b/docs/useCreateController.md
@@ -43,24 +43,24 @@ export const BookCreate = () => {
 
 **Tip**: If you just use the return value of `useCreateController` to put it in an `CreateContext`, use [the `<CreateBase>` component](./CreateBase.md) instead for simpler markup.
 
-`useCreateController` accepts an options argument, with the following fields, all optional:
+## Arguments
 
-* [`disableAuthentication`](./Create.md#disableauthentication): disable the authentication check
-* [`mutationOptions`](./Create.md#mutationoptions): options for the `dataProvider.create()` call
-* [`record`](./Create.md#record): use the provided record as base instead of fetching it
-* [`redirect`](./Create.md#redirect): change the redirect location after successful creation
-* [`resource`](./Create.md#resource): override the name of the resource to create
-* [`transform`](./Create.md#transform): transform the form data before calling `dataProvider.create()`
+`useCreateController` accepts an object with the following keys, all optional:
 
-`useCreateController` returns an object with the following fields:
+* [`disableAuthentication`](./Create.md#disableauthentication): Disable the authentication check
+* [`mutationOptions`](./Create.md#mutationoptions): Options for the `dataProvider.create()` call
+* [`record`](./Create.md#record): Use the provided record as base instead of fetching it
+* [`redirect`](./Create.md#redirect): Change the redirect location after successful creation
+* [`resource`](./Create.md#resource): Override the name of the resource to create
+* [`transform`](./Create.md#transform): Transform the form data before calling `dataProvider.create()`
 
-```jsx
-const {
-    defaultTitle, // the translated title based on the resource, e.g. 'Create New Post'
-    redirect, // the default redirection route. Defaults to 'list'
-    resource, // the resource name, deduced from the location. e.g. 'posts'
-    save, // the update callback, to be passed to the underlying form as submit handler
-    saving, // boolean that becomes true when the dataProvider is called to create the record
-} = useCreateController();
-```
 
+## Return Value
+
+`useCreateController` returns an object with the following keys:
+
+* `defaultTitle`: Translated title based on the resource, e.g. 'Create New Post'
+* `redirect`: Default redirect route. Defaults to 'list'
+* `resource`: Resource name, deduced from the location. e.g. 'posts'
+* `save`: Update callback to be passed to the underlying form as submit handler
+* `saving`: Boolean, `true` when the dataProvider is called to create the record
diff --git a/docs/useEditContext.md b/docs/useEditContext.md
index d918e431846..decb1251d54 100644
--- a/docs/useEditContext.md
+++ b/docs/useEditContext.md
@@ -45,23 +45,19 @@ const Aside = () => {
 
 ## Return Value
 
-The `useEditContext` hook returns an object with the same keys as returned by [`useEditController`](./useEditController.md):
-
-```jsx
-const {
-    defaultTitle, // the translated title based on the resource, e.g. 'Post #123'
-    error,  // error returned by dataProvider when it failed to fetch the record. Useful if you want to adapt the view instead of just showing a notification using the `onError` side effect.
-    isFetching, // boolean that is true while the record is being fetched, and false once the record is fetched
-    isLoading, // boolean that is true until the record is available for the first time
-    mutationMode, // mutation mode argument passed as parameter, or 'undoable' if not defined
-    record, // record fetched via dataProvider.getOne() based on the id from the location
-    redirect, // the default redirection route. Defaults to 'list'
-    refetch, // a function that allows you to refetch the record 
-    resource, // the resource name, deduced from the location. e.g. 'posts'
-    save, // the update callback, to be passed to the underlying form as submit handler
-    saving, // boolean that becomes true when the dataProvider is called to update the record
-} = useEditContext();
-```
+`useEditContext` returns an object with the same keys as [`useEditController`](./useEditController.md):
+
+* `defaultTitle`: Translated title based on the resource, e.g. 'Post #123'
+* `isFetching`: Boolean, `true` while the record is being fetched, `false` once done fetching
+* `isLoading`: Boolean, `true` until the record is available for the first time
+* `mutationMode`: Mutation mode argument passed as parameter, or 'undoable' if not defined
+* `record`: Record fetched via `dataProvider.getOne()` based on the id from the location
+* `redirect`: Default redirection route. Defaults to 'list'
+* `refetch`: Function that allows you to refetch the record 
+* `resource`: Resource name deduced from the location. e.g. 'posts'
+* `save`: Update callback to be passed to the underlying form as submit handler
+* `saving`: Boolean, `true` when `dataProvider` is called to update the record
+* `error`: Error returned by `dataProvider` when it failed to fetch the record. Useful if you want to adapt the view instead of just showing a notification using the `onError` side effect.
 
 ## TypeScript
 
diff --git a/docs/useEditController.md b/docs/useEditController.md
index c8396e83dde..a8f20d6821f 100644
--- a/docs/useEditController.md
+++ b/docs/useEditController.md
@@ -46,31 +46,31 @@ export const BookEdit = () => {
 
 **Tip**: If you just use the return value of `useEditController` to put it in an `EditContext`, use [the `<EditBase>` component](./EditBase.md) instead for simpler markup.
 
-`useEditController` accepts an options argument, with the following fields, all optional:
+## Arguments
 
-* [`disableAuthentication`](./Edit.md#disableauthentication): disable the authentication check
-* [`id`](./Edit.md#id): the id of the record to edit
-* [`mutationMode`](./Edit.md#mutationmode): switch to optimistic or pessimistic mutations (undoable by default)
-* [`mutationOptions`](./Edit.md#mutationoptions): options for the `dataProvider.update()` call
-* [`queryOptions`](./Edit.md#queryoptions): options for the `dataProvider.getOne()` call
-* [`redirect`](./Edit.md#redirect): change the redirect location after successful creation
-* [`resource`](./Edit.md#resource): override the name of the resource to create
-* [`transform`](./Edit.md#transform): transform the form data before calling `dataProvider.update()`
+`useEditController` accepts an object with the following keys, all optional:
 
-`useEditController` returns an object with the following fields:
+* [`disableAuthentication`](./Edit.md#disableauthentication): Disable the authentication check
+* [`id`](./Edit.md#id): The id of the record to edit
+* [`mutationMode`](./Edit.md#mutationmode): Switch to optimistic or pessimistic mutations (undoable by default)
+* [`mutationOptions`](./Edit.md#mutationoptions): Options for the `dataProvider.update()` call
+* [`queryOptions`](./Edit.md#queryoptions): Options for the `dataProvider.getOne()` call
+* [`redirect`](./Edit.md#redirect): Change the redirect location after successful creation
+* [`resource`](./Edit.md#resource): Override the name of the resource to create
+* [`transform`](./Edit.md#transform): Transform the form data before calling `dataProvider.update()`
 
-```jsx
-const {
-    defaultTitle, // the translated title based on the resource, e.g. 'Post #123'
-    error,  // error returned by dataProvider when it failed to fetch the record. Useful if you want to adapt the view instead of just showing a notification using the `onError` side effect.
-    isFetching, // boolean that is true while the record is being fetched, and false once the record is fetched
-    isLoading, // boolean that is true until the record is available for the first time
-    mutationMode, // mutation mode argument passed as parameter, or 'undoable' if not defined
-    record, // record fetched via dataProvider.getOne() based on the id from the location
-    redirect, // the default redirection route. Defaults to 'list'
-    refetch, // a function that allows you to refetch the record 
-    resource, // the resource name, deduced from the location. e.g. 'posts'
-    save, // the update callback, to be passed to the underlying form as submit handler
-    saving, // boolean that becomes true when the dataProvider is called to update the record
-} = useEditController();
-```
+## Return Value
+
+`useEditController` returns an object with the following keys:
+
+* `defaultTitle`: Translated title based on the resource, e.g. 'Post #123'
+* `isFetching`: Boolean, `true` while the record is being fetched, `false` once done fetching
+* `isLoading`: Boolean, `true` until the record is available for the first time
+* `mutationMode`: Mutation mode argument passed as parameter, or 'undoable' if not defined
+* `record`: Record fetched via `dataProvider.getOne()` based on the id from the location
+* `redirect`: Default redirection route. Defaults to 'list'
+* `refetch`: Function that allows you to refetch the record 
+* `resource`: Resource name deduced from the location. e.g. 'posts'
+* `save`: Update callback to be passed to the underlying form as submit handler
+* `saving`: Boolean, `true` when `dataProvider` is called to update the record
+* `error`: Error returned by `dataProvider` when it failed to fetch the record. Useful if you want to adapt the view instead of just showing a notification using the `onError` side effect.
diff --git a/docs/useList.md b/docs/useList.md
index 9611b6ea5a1..860e4b0652b 100644
--- a/docs/useList.md
+++ b/docs/useList.md
@@ -61,12 +61,13 @@ const MyComponent = () => {
     );
 };
 ```
+## Arguments
 
-The `useList` parameter accepts the following options:
+`useList` expects an object with the following keys:
 
 * [`data`](#data)
 * [`filter`](#filter)
-* [`filterCallback](#filtercallback)
+* [`filterCallback`](#filtercallback)
 * [`isFetching`](#isfetching)
 * [`isLoading`](#isloading)
 * [`page`](#page)
@@ -255,39 +256,46 @@ const { data } = useList({
 
 ## Return Value
 
-`useList` returns an object matching the shape of the `ListContext`: 
+`useList` returns an object with keys matching the shape of the `ListContext`: 
 
-```jsx
-const {
-    // fetched data
-    data, // a paginated, sorted, and filtered array of records, e.g. [{ id: 123, title: 'hello world' }, { ... }]
-    total, // the total number of results for the current filters, excluding pagination. Useful to build the pagination controls, e.g. 23      
-    isFetching, // boolean that is true while the data is being fetched, and false once the data is fetched
-    isLoading, // boolean that is true until the data is available for the first time
-    // pagination
-    page, // the current page. Starts at 1
-    perPage, // the number of results per page. Defaults to 1000
-    setPage, // a callback to change the page, e.g. setPage(3)
-    setPerPage, // a callback to change the number of results per page, e.g. setPerPage(25)
-    hasPreviousPage, // boolean, true if the current page is not the first one
-    hasNextPage, // boolean, true if the current page is not the last one
-    // sorting
-    sort, // a sort object { field, order }, e.g. { field: 'date', order: 'DESC' }
-    setSort, // a callback to change the sort, e.g. setSort({ field: 'name', order: 'ASC' })
-    // filtering
-    filterValues, // a dictionary of filter values, e.g. { title: 'lorem', nationality: 'fr' }
-    displayedFilters, // a dictionary of the displayed filters, e.g. { title: true, nationality: true }
-    setFilters, // a callback to update the filters, e.g. setFilters(filters, displayedFilters)
-    showFilter, // a callback to show one of the filters, e.g. showFilter('title', defaultValue)
-    hideFilter, // a callback to hide one of the filters, e.g. hideFilter('title')
-    // record selection
-    selectedIds, // an array listing the ids of the selected rows, e.g. [123, 456]
-    onSelect, // callback to change the list of selected rows, e.g. onSelect([456, 789])
-    onToggleItem, // callback to toggle the selection of a given record based on its id, e.g. onToggleItem(456)
-    onUnselectItems, // callback to clear the selection, e.g. onUnselectItems();
-    // misc
-    defaultTitle, // empty string
-    resource, // undefined
-    refetch, // a function that throws an error, as refetch doesn't make sense for local data
-} = useList({ data });
-```
+**Data**
+
+* `data`: Array of the list records, e.g. `[{ id: 123, title: 'hello world' }, { ... }`
+* `total`: Total number of results for the current filters, excluding pagination. Useful to build the pagination controls, e.g. 23      
+* `isFetching`: Boolean, `true` while the data is being fetched, `false` once the data is fetched
+* `isLoading`: Boolean, `true` until the data is available for the first time
+
+**Pagination**
+
+* `page`: Current page. Starts at 1
+* `perPage`: Number of results per page. Defaults to 25
+* `setPage`: Callback to change the page, e.g. `setPage(3)`
+* `setPerPage`: Callback to change the number of results per page, e.g. `setPerPage(25)`
+* `hasPreviousPage`: Boolean, `true` if the current page is not the first one
+* `hasNextPage`: Boolean, `true` if the current page is not the last one
+
+**Sorting**
+
+* `sort`: Sort object `{ field, order }`, e.g. `{ field: 'date', order: 'DESC' }`
+* `setSort`: Callback to change the sort, e.g. `setSort({ field: 'name', order: 'ASC' })`
+
+**Filtering**
+
+* `filterValues`: Dictionary of filter values, e.g. `{ title: 'lorem', nationality: 'fr' }`
+* `displayedFilters`: Dictionary of displayed filters, e.g. `{ title: true, nationality: true }`
+* `setFilters`: Callback to update the filters, e.g. `setFilters(filters, displayedFilters)`
+* `showFilter`: Callback to show one of the filters, e.g. `showFilter('title', defaultValue)`
+* `hideFilter`: Callback to hide one of the filters, e.g. `hideFilter('title')`
+
+**Record selection**
+
+* `selectedIds`: Array listing the ids of the selected records, e.g. `[123, 456]`
+* `onSelect`: Callback to change the list of selected records, e.g. `onSelect([456, 789])`
+* `onToggleItem`: Callback to toggle the record selection for a given id, e.g. `onToggleItem(456)`
+* `onUnselectItems`: Callback to clear the record selection, e.g. `onUnselectItems();`
+
+**Misc**
+
+* `defaultTitle`: Translated title based on the resource, e.g. 'Posts'
+* `resource`: Resource name, deduced from the location. e.g. 'posts'
+* `refetch`: Callback for fetching the list data again
diff --git a/docs/useListContext.md b/docs/useListContext.md
index 8e2983d94c2..88e913a50e6 100644
--- a/docs/useListContext.md
+++ b/docs/useListContext.md
@@ -56,42 +56,49 @@ export const PostList = () => (
 
 ## Return Value
 
-The `useListContext` hook returns an object with the following keys:
+`useListContext` returns an object with the following keys:
 
-```jsx
-const {
-    // fetched data
-    data, // an array of the list records, e.g. [{ id: 123, title: 'hello world' }, { ... }]
-    total, // the total number of results for the current filters, excluding pagination. Useful to build the pagination controls, e.g. 23      
-    isFetching, // boolean that is true while the data is being fetched, and false once the data is fetched
-    isLoading, // boolean that is true until the data is available for the first time
-    // pagination
-    page, // the current page. Starts at 1
-    perPage, // the number of results per page. Defaults to 25
-    setPage, // a callback to change the page, e.g. setPage(3)
-    setPerPage, // a callback to change the number of results per page, e.g. setPerPage(25)
-    hasPreviousPage, // boolean, true if the current page is not the first one
-    hasNextPage, // boolean, true if the current page is not the last one
-    // sorting
-    sort, // a sort object { field, order }, e.g. { field: 'date', order: 'DESC' }
-    setSort, // a callback to change the sort, e.g. setSort({ field: 'name', order: 'ASC' })
-    // filtering
-    filterValues, // a dictionary of filter values, e.g. { title: 'lorem', nationality: 'fr' }
-    displayedFilters, // a dictionary of the displayed filters, e.g. { title: true, nationality: true }
-    setFilters, // a callback to update the filters, e.g. setFilters(filters, displayedFilters)
-    showFilter, // a callback to show one of the filters, e.g. showFilter('title', defaultValue)
-    hideFilter, // a callback to hide one of the filters, e.g. hideFilter('title')
-    // record selection
-    selectedIds, // an array listing the ids of the selected rows, e.g. [123, 456]
-    onSelect, // callback to change the list of selected rows, e.g. onSelect([456, 789])
-    onToggleItem, // callback to toggle the selection of a given record based on its id, e.g. onToggleItem(456)
-    onUnselectItems, // callback to clear the selection, e.g. onUnselectItems();
-    // misc
-    defaultTitle, // the translated title based on the resource, e.g. 'Posts'
-    resource, // the resource name, deduced from the location. e.g. 'posts'
-    refetch, // callback for fetching the list data again
-} = useListContext();
-```
+**Data**
+
+* `data`: Array of the list records, e.g. `[{ id: 123, title: 'hello world' }, { ... }`
+* `total`: Total number of results for the current filters, excluding pagination. Useful to build the pagination controls, e.g. 23      
+* `isFetching`: Boolean, `true` while the data is being fetched, `false` once the data is fetched
+* `isLoading`: Boolean, `true` until the data is available for the first time
+
+**Pagination**
+
+* `page`: Current page. Starts at 1
+* `perPage`: Number of results per page. Defaults to 25
+* `setPage`: Callback to change the page, e.g. `setPage(3)`
+* `setPerPage`: Callback to change the number of results per page, e.g. `setPerPage(25)`
+* `hasPreviousPage`: Boolean, `true` if the current page is not the first one
+* `hasNextPage`: Boolean, `true` if the current page is not the last one
+
+**Sorting**
+
+* `sort`: Sort object `{ field, order }`, e.g. `{ field: 'date', order: 'DESC' }`
+* `setSort`: Callback to change the sort, e.g. `setSort({ field: 'name', order: 'ASC' })`
+
+**Filtering**
+
+* `filterValues`: Dictionary of filter values, e.g. `{ title: 'lorem', nationality: 'fr' }`
+* `displayedFilters`: Dictionary of displayed filters, e.g. `{ title: true, nationality: true }`
+* `setFilters`: Callback to update the filters, e.g. `setFilters(filters, displayedFilters)`
+* `showFilter`: Callback to show one of the filters, e.g. `showFilter('title', defaultValue)`
+* `hideFilter`: Callback to hide one of the filters, e.g. `hideFilter('title')`
+
+**Record selection**
+
+* `selectedIds`: Array listing the ids of the selected records, e.g. `[123, 456]`
+* `onSelect`: Callback to change the list of selected records, e.g. `onSelect([456, 789])`
+* `onToggleItem`: Callback to toggle the record selection for a given id, e.g. `onToggleItem(456)`
+* `onUnselectItems`: Callback to clear the record selection, e.g. `onUnselectItems();`
+
+**Misc**
+
+* `defaultTitle`: Translated title based on the resource, e.g. 'Posts'
+* `resource`: Resource name, deduced from the location. e.g. 'posts'
+* `refetch`: Callback for fetching the list data again
 
 ## Declarative Version
 
diff --git a/docs/useListController.md b/docs/useListController.md
index 33d8a2a926a..5f5217d0eee 100644
--- a/docs/useListController.md
+++ b/docs/useListController.md
@@ -29,21 +29,21 @@ const MyList = () => {
 };
 ```
 
-## Input Format
-
-`useListController` expects one object as parameter. All keys are optional.
-
-* [`debounce`](./List.md#debounce): debounce time in ms for the setFilters callbacks
-* [`disableAuthentication`](./List.md#disableauthentication): set to true to allow anonymous access to the list
-* [`disableSyncWithLocation`](./List.md#disablesyncwithlocation): set to true to have more than one list per page
-* [`exporter`](./List.md#exporter): exporter function
-* [`filter`](./List.md#filter-permanent-filter): permanent filter, forced over the user filter
-* [`filterDefaultValues`](./List.md#filterdefaultvalues): default values for the filter form
-* [`perPage`](./List.md#perpage): number of results per page
-* [`queryOptions`](./List.md#queryoptions): react-query options for the useQuery call
-* [`resource`](./List.md#resource): resource name, e.g. 'posts' ; defaults to the current resource context
-* [`sort`](./List.md#sort), current sort value, e.g. `{ field: 'published_at', order: 'DESC' }`
-* [`storeKey`](#storekey): key used to differentiate the list from another sharing the same resource, in store managed states
+## Arguments
+
+`useListController` expects an object as parameter. All keys are optional.
+
+* [`debounce`](./List.md#debounce): Debounce time in ms for the setFilters callbacks
+* [`disableAuthentication`](./List.md#disableauthentication): Set to true to allow anonymous access to the list
+* [`disableSyncWithLocation`](./List.md#disablesyncwithlocation): Set to true to have more than one list per page
+* [`exporter`](./List.md#exporter): Exporter function
+* [`filter`](./List.md#filter-permanent-filter): Permanent filter, forced over the user filter
+* [`filterDefaultValues`](./List.md#filterdefaultvalues): Default values for the filter form
+* [`perPage`](./List.md#perpage): Number of results per page
+* [`queryOptions`](./List.md#queryoptions): React-query options for the useQuery call
+* [`resource`](./List.md#resource): Resource name, e.g. 'posts' ; defaults to the current resource context
+* [`sort`](./List.md#sort): Current sort value, e.g. `{ field: 'published_at', order: 'DESC' }`
+* [`storeKey`](#storekey): Key used to differentiate the list from another sharing the same resource, in store managed states
 
 Here are their default values:
 
@@ -141,39 +141,46 @@ You can disable this feature by setting the `storeKey` prop to `false`. When dis
 
 ## Return Value
 
-The return value of `useListController` has the following shape:
-
-```js
-const {
-    // fetched data
-    data, // an array of the list records, e.g. [{ id: 123, title: 'hello world' }, { ... }]
-    total, // the total number of results for the current filters, excluding pagination. Useful to build the pagination controls, e.g. 23      
-    isFetching, // boolean that is true while the data is being fetched, and false once the data is fetched
-    isLoading, // boolean that is true until the data is available for the first time
-    // pagination
-    page, // the current page. Starts at 1
-    perPage, // the number of results per page. Defaults to 25
-    setPage, // a callback to change the page, e.g. setPage(3)
-    setPerPage, // a callback to change the number of results per page, e.g. setPerPage(25)
-    hasPreviousPage, // boolean, true if the current page is not the first one
-    hasNextPage, // boolean, true if the current page is not the last one
-    // sorting
-    sort, // a sort object { field, order }, e.g. { field: 'date', order: 'DESC' }
-    setSort, // a callback to change the sort, e.g. setSort({ field: 'name', order: 'ASC' })
-    // filtering
-    filterValues, // a dictionary of filter values, e.g. { title: 'lorem', nationality: 'fr' }
-    displayedFilters, // a dictionary of the displayed filters, e.g. { title: true, nationality: true }
-    setFilters, // a callback to update the filters, e.g. setFilters(filters, displayedFilters)
-    showFilter, // a callback to show one of the filters, e.g. showFilter('title', defaultValue)
-    hideFilter, // a callback to hide one of the filters, e.g. hideFilter('title')
-    // record selection
-    selectedIds, // an array listing the ids of the selected rows, e.g. [123, 456]
-    onSelect, // callback to change the list of selected rows, e.g. onSelect([456, 789])
-    onToggleItem, // callback to toggle the selection of a given record based on its id, e.g. onToggleItem(456)
-    onUnselectItems, // callback to clear the selection, e.g. onUnselectItems();
-    // misc
-    defaultTitle, // the translated title based on the resource, e.g. 'Posts'
-    resource, // the resource name, deduced from the location. e.g. 'posts'
-    refetch, // callback for fetching the list data again
-} = listContext;
-```
+`useListController` returns an object with the following keys: 
+
+**Data**
+
+* `data`: Array of the list records, e.g. `[{ id: 123, title: 'hello world' }, { ... }`
+* `total`: Total number of results for the current filters, excluding pagination. Useful to build the pagination controls, e.g. 23      
+* `isFetching`: Boolean, `true` while the data is being fetched, `false` once the data is fetched
+* `isLoading`: Boolean, `true` until the data is available for the first time
+
+**Pagination**
+
+* `page`: Current page. Starts at 1
+* `perPage`: Number of results per page. Defaults to 25
+* `setPage`: Callback to change the page, e.g. `setPage(3)`
+* `setPerPage`: Callback to change the number of results per page, e.g. `setPerPage(25)`
+* `hasPreviousPage`: Boolean, `true` if the current page is not the first one
+* `hasNextPage`: Boolean, `true` if the current page is not the last one
+
+**Sorting**
+
+* `sort`: Sort object `{ field, order }`, e.g. `{ field: 'date', order: 'DESC' }`
+* `setSort`: Callback to change the sort, e.g. `setSort({ field: 'name', order: 'ASC' })`
+
+**Filtering**
+
+* `filterValues`: Dictionary of filter values, e.g. `{ title: 'lorem', nationality: 'fr' }`
+* `displayedFilters`: Dictionary of displayed filters, e.g. `{ title: true, nationality: true }`
+* `setFilters`: Callback to update the filters, e.g. `setFilters(filters, displayedFilters)`
+* `showFilter`: Callback to show one of the filters, e.g. `showFilter('title', defaultValue)`
+* `hideFilter`: Callback to hide one of the filters, e.g. `hideFilter('title')`
+
+**Record selection**
+
+* `selectedIds`: Array listing the ids of the selected records, e.g. `[123, 456]`
+* `onSelect`: Callback to change the list of selected records, e.g. `onSelect([456, 789])`
+* `onToggleItem`: Callback to toggle the record selection for a given id, e.g. `onToggleItem(456)`
+* `onUnselectItems`: Callback to clear the record selection, e.g. `onUnselectItems();`
+
+**Misc**
+
+* `defaultTitle`: Translated title based on the resource, e.g. 'Posts'
+* `resource`: Resource name, deduced from the location. e.g. 'posts'
+* `refetch`: Callback for fetching the list data again
diff --git a/docs/useRegisterMutationMiddleware.md b/docs/useRegisterMutationMiddleware.md
index 41fd4665262..2d90ddfdf66 100644
--- a/docs/useRegisterMutationMiddleware.md
+++ b/docs/useRegisterMutationMiddleware.md
@@ -58,9 +58,9 @@ React-admin will wrap each call to the `dataProvider.create()` mutation with the
 
 `useRegisterMutationMiddleware` unregisters the middleware function when the component unmounts. For this to work correctly, you must provide a stable reference to the function by wrapping it in a `useCallback` hook for instance.
 
-## Params
+## Arguments
 
-`useRegisterMutationMiddleware` expects a single parameter: a middleware function.
+`useRegisterMutationMiddleware` expects a single argument: a middleware function.
 
 A middleware function must have the following signature:
 
diff --git a/docs/useSaveContext.md b/docs/useSaveContext.md
index 0bd80181fa4..e88931f858c 100644
--- a/docs/useSaveContext.md
+++ b/docs/useSaveContext.md
@@ -14,11 +14,7 @@ title: "useSaveContext"
 ```jsx
 import { useSaveContext } from 'react-admin';
 
-const { 
-    save, // the create or update callback, which receives the form data and calls the dataProvider
-    saving, //  boolean that becomes true when the dataProvider is called
-    mutationMode, // the current mutation mode, either 'undoable', 'optimistic', or 'pessimistic'
-} = useSaveContext();
+const { save, saving, mutationMode } = useSaveContext();
 ```
 
 You can create a custom `SaveContext` to override the default `save` callback:
@@ -41,3 +37,11 @@ const MyComponent = () => {
 }
 ```
 {% endraw %}
+
+## Return Value
+
+`useSaveContext` returns an object with the following keys:
+
+* `save`: Create or update callback which receives form data and calls `dataProvider`
+* `saving`: Boolean, `true` when `dataProvider` is called
+* `mutationMode`: Current mutation mode, either 'undoable', 'optimistic' or 'pessimistic'
diff --git a/docs/useShowContext.md b/docs/useShowContext.md
index 9a20f7acce4..5356e8f80e5 100644
--- a/docs/useShowContext.md
+++ b/docs/useShowContext.md
@@ -15,22 +15,16 @@ You can use `useShowContext` inside show components to access the data computed
 import { useShowContext, SimpleShowLayout, Show } from 'react-admin';
 
 const PostShowLayout = () => {
-    const {
-        defaultTitle, // the translated title based on the resource, e.g. 'Post #123'
-        error,  // error returned by dataProvider when it failed to fetch the record. Useful if you want to adapt the view instead of just showing a notification using the `onError` side effect.
-        isFetching, // boolean that is true while the record is being fetched, and false once the record is fetched
-        isLoading, // boolean that is true until the record is available for the first time
-        record, // record fetched via dataProvider.getOne() based on the id from the location
-        refetch, // callback to refetch the record via dataProvider.getOne()
-        resource, // the resource name, deduced from the location. e.g. 'posts'
-    } = useShowContext();
+    const { defaultTitle, error, isLoading } = useShowContext();
 
     if (isLoading) {
         return <div>Loading...</div>;
     }
+
     if (error) {
         return <div>Error!</div>;
     }
+
     return (
         <>
             <h1>{defaultTitle}</h1>
@@ -49,6 +43,19 @@ const PostShow = () => (
 )
 ```
 
+## Return Value
+
+`useShowContext` returns an object with the same keys as [`useShowController`](./useShowController.md):
+
+* `defaultTitle`: Translated title based on the resource, e.g. 'Post #123'
+* `isFetching`: Boolean, `true` while the record is being fetched, and false once done fetching
+* `isLoading`: Boolean, `true` until the record is available for the first time
+* `record`: Record fetched via `dataProvider.getOne()` based on the id from the location
+* `refetch`: Callback to refetch the record via `dataProvider.getOne()`
+* `resource`: The resource name, deduced from the location. e.g. 'posts'
+* `error`: Error returned by dataProvider when it failed to fetch the record. Useful if you want to adapt the view instead of just showing a notification using the `onError` side effect.
+
+
 ## TypeScript
 
 The `useShowContext` hook accepts a generic parameter for the record type:
diff --git a/docs/useShowController.md b/docs/useShowController.md
index 5d5f183d858..53ac156b79e 100644
--- a/docs/useShowController.md
+++ b/docs/useShowController.md
@@ -21,15 +21,7 @@ You can use `useShowController` to create your own custom Show view, like this o
 import { useShowController, RecordContextProvider, SimpleShowLayout } from 'react-admin';
 
 const PostShow = () => {
-    const {
-        defaultTitle, // the translated title based on the resource, e.g. 'Post #123'
-        error,  // error returned by dataProvider when it failed to fetch the record. Useful if you want to adapt the view instead of just showing a notification using the `onError` side effect.
-        isFetching, // boolean that is true while the record is being fetched, and false once the record is fetched
-        isLoading, // boolean that is true until the record is available for the first time
-        record, // record fetched via dataProvider.getOne() based on the id from the location
-        refetch, // callback to refetch the record via dataProvider.getOne()
-        resource, // the resource name, deduced from the location. e.g. 'posts'
-    } = useShowController();
+    const { defaultTitle, error, isLoading, record } = useShowController();
 
     if (isLoading) {
         return <div>Loading...</div>;
@@ -53,16 +45,14 @@ This custom Show view has no action buttons - it's up to you to add them in pure
 
 **Tip**: Use [`<ShowBase>`](./ShowBase.md) instead of `useShowController` if you need a component version of that hook.
 
-## Parameters
+## Arguments
 
-`useShowController` expects one parameter argument. It's an object with the following attributes: 
+`useShowController` accepts an object with the following keys, all optional: 
 
-| Name             | Required | Type              | Default | Description
-|------------------|----------|-------------------|---------|--------------------------------------------------------
-| `disable Authentication` | Optional | `boolean` |         | Set to `true` to disable the authentication check.
-| `id`             | Optional | `string`          |         | The record identifier. If not provided, it will be deduced from the URL.
-| `queryOptions`   | Optional | `object`          |         | The options to pass to the [`useQuery`](./Actions.mdl#usequery-and-usemutation) hook.
-| `resource`       | Optional | `string`          |         | The resource name, e.g. `posts`
+* [`disableAuthentication`](#disableauthentication): Boolean, set to `true` to disable the authentication check.
+* [`id`](#id): Record identifier. If not provided, it will be deduced from the URL.
+* [`queryOptions`](#queryoptions): Options object to pass to the [`useQuery`](./Actions.mdl#usequery-and-usemutation) hook.
+* [`resource`](#resource): Resource name, e.g. `posts`
 
 ## `disableAuthentication`
 
@@ -176,6 +166,18 @@ const PostShow = () => {
 };
 ```
 
+## Return Value
+
+`useShowController` returns an object with the following keys:
+
+* `defaultTitle`: Translated title based on the resource, e.g. 'Post #123'
+* `isFetching`: Boolean, `true` while the record is being fetched, and false once done fetching
+* `isLoading`: Boolean, `true` until the record is available for the first time
+* `record`: Record fetched via `dataProvider.getOne()` based on the id from the location
+* `refetch`: Callback to refetch the record via `dataProvider.getOne()`
+* `resource`: The resource name, deduced from the location. e.g. 'posts'
+* `error`: Error returned by dataProvider when it failed to fetch the record. Useful if you want to adapt the view instead of just showing a notification using the `onError` side effect.
+
 ## Controlled Mode
 
 By default, `useShowController` reads the resource name from the resource context, and the record id from the browser location.
diff --git a/docs/useUnique.md b/docs/useUnique.md
index 7eb6a2dfa83..6dd3b61c7d8 100644
--- a/docs/useUnique.md
+++ b/docs/useUnique.md
@@ -30,14 +30,16 @@ const UserCreateForm = () => {
 };
 ```
 
-## Options
-
-| Option              | Required | Type           | Default  | Description                                                                        |
-| ------------------- | -------- | -------------- | -------- | ---------------------------------------------------------------------------------- |
-| `message`           | Optional | `string`       | `ra.validation.unique` | A custom message to display when the validation fails                |
-| `debounce`          | Optional | `number`       | 1000                   | The number of milliseconds to wait for new changes before validating |
-| `filter`            | Optional | `object`       | -                      | Additional filters to pass to the `dataProvider.getList` call        |
-| `resource`          | Optional | `string`       | current from Context   | The resource targeted by the `dataProvider.getList` call             |
+## Arguments
+
+`useUnique` accepts an object with the following keys, all optional: 
+
+| Key                     | Type           | Default                | Description                                                          |
+| ----------------------- | -------------- | ---------------------- | -------------------------------------------------------------------- |
+| [`message`](#message)   | `string`       | `ra.validation.unique` | A custom message to display when the validation fails                |
+| [`debounce`](#debounce) | `number`       | 1000                   | The number of milliseconds to wait for new changes before validating |
+| [`filter`](#filter)     | `object`       | -                      | Additional filters to pass to the `dataProvider.getList` call        |
+| [`resource`](#resource) | `string`       | current from Context   | The resource targeted by the `dataProvider.getList` call             |
 
 ## `message`
 

From a786c305681e172b221bf08c1dedd3516caaca3b Mon Sep 17 00:00:00 2001
From: sebashwa <sebastian@priorist.com>
Date: Fri, 17 Nov 2023 00:01:09 +0100
Subject: [PATCH 3/6] Add links to caching page in hook docs

The record returned by useRecordContext, useShowController, useShowContext,
useEditController and useEditContext is sometimes a cached version of
the record or undefined.

This is now stated more explicitly in the docs and a link to
the caching page is added.
---
 docs/useEditContext.md    | 2 +-
 docs/useEditController.md | 2 +-
 docs/useRecordContext.md  | 2 +-
 docs/useShowContext.md    | 2 +-
 docs/useShowController.md | 2 +-
 5 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/docs/useEditContext.md b/docs/useEditContext.md
index decb1251d54..4b64ebf1450 100644
--- a/docs/useEditContext.md
+++ b/docs/useEditContext.md
@@ -51,7 +51,7 @@ const Aside = () => {
 * `isFetching`: Boolean, `true` while the record is being fetched, `false` once done fetching
 * `isLoading`: Boolean, `true` until the record is available for the first time
 * `mutationMode`: Mutation mode argument passed as parameter, or 'undoable' if not defined
-* `record`: Record fetched via `dataProvider.getOne()` based on the id from the location
+* `record`: Either the record fetched via `dataProvider.getOne()` based on the id from the location, a cached version of the record (see also [Caching](./Caching.md#optimistic-rendering)) or `undefined`
 * `redirect`: Default redirection route. Defaults to 'list'
 * `refetch`: Function that allows you to refetch the record 
 * `resource`: Resource name deduced from the location. e.g. 'posts'
diff --git a/docs/useEditController.md b/docs/useEditController.md
index a8f20d6821f..11756313d73 100644
--- a/docs/useEditController.md
+++ b/docs/useEditController.md
@@ -67,7 +67,7 @@ export const BookEdit = () => {
 * `isFetching`: Boolean, `true` while the record is being fetched, `false` once done fetching
 * `isLoading`: Boolean, `true` until the record is available for the first time
 * `mutationMode`: Mutation mode argument passed as parameter, or 'undoable' if not defined
-* `record`: Record fetched via `dataProvider.getOne()` based on the id from the location
+* `record`: Either the record fetched via `dataProvider.getOne()` based on the id from the location, a cached version of the record (see also [Caching](./Caching.md#optimistic-rendering)) or `undefined` 
 * `redirect`: Default redirection route. Defaults to 'list'
 * `refetch`: Function that allows you to refetch the record 
 * `resource`: Resource name deduced from the location. e.g. 'posts'
diff --git a/docs/useRecordContext.md b/docs/useRecordContext.md
index 14c44fd77da..b79b09214e3 100644
--- a/docs/useRecordContext.md
+++ b/docs/useRecordContext.md
@@ -32,7 +32,7 @@ const BookShow = () => (
 
 ## Optimistic Rendering
 
-As react-admin uses optimistic rendering, `useRecordContext` may return an undefined record on load. Make sure you prepare for that! 
+As react-admin uses optimistic rendering, `useRecordContext` may be `undefined` or a cached version of the record on load (see also [Caching](./Caching.md#optimistic-rendering)). Make sure you prepare for that! 
 
 ```jsx
 const BookAuthor = () => {
diff --git a/docs/useShowContext.md b/docs/useShowContext.md
index 5356e8f80e5..e0db8430c75 100644
--- a/docs/useShowContext.md
+++ b/docs/useShowContext.md
@@ -50,7 +50,7 @@ const PostShow = () => (
 * `defaultTitle`: Translated title based on the resource, e.g. 'Post #123'
 * `isFetching`: Boolean, `true` while the record is being fetched, and false once done fetching
 * `isLoading`: Boolean, `true` until the record is available for the first time
-* `record`: Record fetched via `dataProvider.getOne()` based on the id from the location
+* `record`: Either the record fetched via `dataProvider.getOne()` based on the id from the location, a cached version of the record (see also [Caching](./Caching.md#optimistic-rendering)) or `undefined` 
 * `refetch`: Callback to refetch the record via `dataProvider.getOne()`
 * `resource`: The resource name, deduced from the location. e.g. 'posts'
 * `error`: Error returned by dataProvider when it failed to fetch the record. Useful if you want to adapt the view instead of just showing a notification using the `onError` side effect.
diff --git a/docs/useShowController.md b/docs/useShowController.md
index 53ac156b79e..ac24e0c94d0 100644
--- a/docs/useShowController.md
+++ b/docs/useShowController.md
@@ -173,7 +173,7 @@ const PostShow = () => {
 * `defaultTitle`: Translated title based on the resource, e.g. 'Post #123'
 * `isFetching`: Boolean, `true` while the record is being fetched, and false once done fetching
 * `isLoading`: Boolean, `true` until the record is available for the first time
-* `record`: Record fetched via `dataProvider.getOne()` based on the id from the location
+* `record`: Either the record fetched via `dataProvider.getOne()` based on the id from the location, a cached version of the record (see also [Caching](./Caching.md#optimistic-rendering)) or `undefined` 
 * `refetch`: Callback to refetch the record via `dataProvider.getOne()`
 * `resource`: The resource name, deduced from the location. e.g. 'posts'
 * `error`: Error returned by dataProvider when it failed to fetch the record. Useful if you want to adapt the view instead of just showing a notification using the `onError` side effect.

From dd4aa481122bb9c2d8154770f5e8d4e6be244772 Mon Sep 17 00:00:00 2001
From: sebashwa <sebastian@priorist.com>
Date: Tue, 5 Dec 2023 22:19:57 +0100
Subject: [PATCH 4/6] Rename arguments headings to parameters

---
 docs/useCreateController.md           | 2 +-
 docs/useEditController.md             | 2 +-
 docs/useList.md                       | 2 +-
 docs/useListController.md             | 2 +-
 docs/useRegisterMutationMiddleware.md | 2 +-
 docs/useShowController.md             | 2 +-
 docs/useUnique.md                     | 2 +-
 7 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/docs/useCreateController.md b/docs/useCreateController.md
index d1cf98469ab..6ca02f306f5 100644
--- a/docs/useCreateController.md
+++ b/docs/useCreateController.md
@@ -43,7 +43,7 @@ export const BookCreate = () => {
 
 **Tip**: If you just use the return value of `useCreateController` to put it in an `CreateContext`, use [the `<CreateBase>` component](./CreateBase.md) instead for simpler markup.
 
-## Arguments
+## Parameters
 
 `useCreateController` accepts an object with the following keys, all optional:
 
diff --git a/docs/useEditController.md b/docs/useEditController.md
index 11756313d73..f962cf0b664 100644
--- a/docs/useEditController.md
+++ b/docs/useEditController.md
@@ -46,7 +46,7 @@ export const BookEdit = () => {
 
 **Tip**: If you just use the return value of `useEditController` to put it in an `EditContext`, use [the `<EditBase>` component](./EditBase.md) instead for simpler markup.
 
-## Arguments
+## Parameters
 
 `useEditController` accepts an object with the following keys, all optional:
 
diff --git a/docs/useList.md b/docs/useList.md
index 860e4b0652b..b21afc00be9 100644
--- a/docs/useList.md
+++ b/docs/useList.md
@@ -61,7 +61,7 @@ const MyComponent = () => {
     );
 };
 ```
-## Arguments
+## Parameters
 
 `useList` expects an object with the following keys:
 
diff --git a/docs/useListController.md b/docs/useListController.md
index 5f5217d0eee..a7d9c68f828 100644
--- a/docs/useListController.md
+++ b/docs/useListController.md
@@ -29,7 +29,7 @@ const MyList = () => {
 };
 ```
 
-## Arguments
+## Parameters
 
 `useListController` expects an object as parameter. All keys are optional.
 
diff --git a/docs/useRegisterMutationMiddleware.md b/docs/useRegisterMutationMiddleware.md
index 2d90ddfdf66..05748392a5b 100644
--- a/docs/useRegisterMutationMiddleware.md
+++ b/docs/useRegisterMutationMiddleware.md
@@ -58,7 +58,7 @@ React-admin will wrap each call to the `dataProvider.create()` mutation with the
 
 `useRegisterMutationMiddleware` unregisters the middleware function when the component unmounts. For this to work correctly, you must provide a stable reference to the function by wrapping it in a `useCallback` hook for instance.
 
-## Arguments
+## Parameters
 
 `useRegisterMutationMiddleware` expects a single argument: a middleware function.
 
diff --git a/docs/useShowController.md b/docs/useShowController.md
index ac24e0c94d0..b8be2360146 100644
--- a/docs/useShowController.md
+++ b/docs/useShowController.md
@@ -45,7 +45,7 @@ This custom Show view has no action buttons - it's up to you to add them in pure
 
 **Tip**: Use [`<ShowBase>`](./ShowBase.md) instead of `useShowController` if you need a component version of that hook.
 
-## Arguments
+## Parameters
 
 `useShowController` accepts an object with the following keys, all optional: 
 
diff --git a/docs/useUnique.md b/docs/useUnique.md
index 6dd3b61c7d8..0e482f5def9 100644
--- a/docs/useUnique.md
+++ b/docs/useUnique.md
@@ -30,7 +30,7 @@ const UserCreateForm = () => {
 };
 ```
 
-## Arguments
+## Parameters
 
 `useUnique` accepts an object with the following keys, all optional: 
 

From a8dfbe9463c1780d8330c37869c3a496ef1051ba Mon Sep 17 00:00:00 2001
From: sebashwa <sebastian@priorist.com>
Date: Tue, 5 Dec 2023 22:43:53 +0100
Subject: [PATCH 5/6] Revert documentation style changes

Document hooks return values as code blocks with comments.
Remove links to Caching page with hints to caching page, as it's not
possible to link to other pages from within codeblocks.
---
 docs/useCreateContext.md    | 14 ++++---
 docs/useCreateController.md | 14 ++++---
 docs/useEditContext.md      | 26 +++++++------
 docs/useEditController.md   | 27 +++++++------
 docs/useList.md             | 75 +++++++++++++++++--------------------
 docs/useListController.md   | 75 +++++++++++++++++--------------------
 docs/useSaveContext.md      | 10 +++--
 docs/useShowContext.md      | 19 ++++++----
 docs/useShowController.md   | 18 +++++----
 9 files changed, 146 insertions(+), 132 deletions(-)

diff --git a/docs/useCreateContext.md b/docs/useCreateContext.md
index 8e02439376a..19c7e9554fc 100644
--- a/docs/useCreateContext.md
+++ b/docs/useCreateContext.md
@@ -42,8 +42,12 @@ const PostCreateForm = () => {
 
 `useCreateContext` returns an object with the same keys as [`useCreateController`](./useCreateController.md):
 
-* `defaultTitle`: Translated title based on the resource, e.g. 'Create New Post'
-* `redirect`: Default redirect route. Defaults to 'list'
-* `resource`: Resource name, deduced from the location. e.g. 'posts'
-* `save`: Update callback to be passed to the underlying form as submit handler
-* `saving`: Boolean, `true` when the dataProvider is called to create the record
+```jsx
+const {
+    defaultTitle, // Translated title based on the resource, e.g. 'Create New Post'
+    redirect, // Default redirect route. Defaults to 'list'
+    resource, // Resource name, deduced from the location. e.g. 'posts'
+    save, // Update callback to be passed to the underlying form as submit handler
+    saving, // Boolean, true when the dataProvider is called to create the record
+} = useCreateContext();
+```
diff --git a/docs/useCreateController.md b/docs/useCreateController.md
index 6ca02f306f5..ed42d1d31d6 100644
--- a/docs/useCreateController.md
+++ b/docs/useCreateController.md
@@ -59,8 +59,12 @@ export const BookCreate = () => {
 
 `useCreateController` returns an object with the following keys:
 
-* `defaultTitle`: Translated title based on the resource, e.g. 'Create New Post'
-* `redirect`: Default redirect route. Defaults to 'list'
-* `resource`: Resource name, deduced from the location. e.g. 'posts'
-* `save`: Update callback to be passed to the underlying form as submit handler
-* `saving`: Boolean, `true` when the dataProvider is called to create the record
+```jsx
+const {
+    defaultTitle, // Translated title based on the resource, e.g. 'Create New Post'
+    redirect, // Default redirect route. Defaults to 'list'
+    resource, // Resource name, deduced from the location. e.g. 'posts'
+    save, // Update callback to be passed to the underlying form as submit handler
+    saving, // Boolean, true when the dataProvider is called to create the record
+} = useCreateController();
+```
diff --git a/docs/useEditContext.md b/docs/useEditContext.md
index 4b64ebf1450..184c8ce7291 100644
--- a/docs/useEditContext.md
+++ b/docs/useEditContext.md
@@ -47,17 +47,21 @@ const Aside = () => {
 
 `useEditContext` returns an object with the same keys as [`useEditController`](./useEditController.md):
 
-* `defaultTitle`: Translated title based on the resource, e.g. 'Post #123'
-* `isFetching`: Boolean, `true` while the record is being fetched, `false` once done fetching
-* `isLoading`: Boolean, `true` until the record is available for the first time
-* `mutationMode`: Mutation mode argument passed as parameter, or 'undoable' if not defined
-* `record`: Either the record fetched via `dataProvider.getOne()` based on the id from the location, a cached version of the record (see also [Caching](./Caching.md#optimistic-rendering)) or `undefined`
-* `redirect`: Default redirection route. Defaults to 'list'
-* `refetch`: Function that allows you to refetch the record 
-* `resource`: Resource name deduced from the location. e.g. 'posts'
-* `save`: Update callback to be passed to the underlying form as submit handler
-* `saving`: Boolean, `true` when `dataProvider` is called to update the record
-* `error`: Error returned by `dataProvider` when it failed to fetch the record. Useful if you want to adapt the view instead of just showing a notification using the `onError` side effect.
+```jsx
+const {
+    defaultTitle, // Translated title based on the resource, e.g. 'Post #123'
+    isFetching, // Boolean, true while the record is being fetched, false once done fetching
+    isLoading, // Boolean, true until the record is available for the first time
+    mutationMode, // Mutation mode argument passed as parameter, or 'undoable' if not defined
+    record, // Either the record fetched via dataProvider.getOne() based on the id from the location, a cached version of the record (see also the Caching documentation page) or undefined
+    redirect, // Default redirection route. Defaults to 'list'
+    refetch, // Function that allows you to refetch the record 
+    resource, // Resource name deduced from the location. e.g. 'posts'
+    save, // Update callback to be passed to the underlying form as submit handler
+    saving, // Boolean, true when dataProvider is called to update the record
+    error, // Error returned by dataProvider when it failed to fetch the record. Useful if you want to adapt the view instead of just showing a notification using the onError side effect.
+} = useEditContext();
+```
 
 ## TypeScript
 
diff --git a/docs/useEditController.md b/docs/useEditController.md
index f962cf0b664..236e91dc664 100644
--- a/docs/useEditController.md
+++ b/docs/useEditController.md
@@ -63,14 +63,19 @@ export const BookEdit = () => {
 
 `useEditController` returns an object with the following keys:
 
-* `defaultTitle`: Translated title based on the resource, e.g. 'Post #123'
-* `isFetching`: Boolean, `true` while the record is being fetched, `false` once done fetching
-* `isLoading`: Boolean, `true` until the record is available for the first time
-* `mutationMode`: Mutation mode argument passed as parameter, or 'undoable' if not defined
-* `record`: Either the record fetched via `dataProvider.getOne()` based on the id from the location, a cached version of the record (see also [Caching](./Caching.md#optimistic-rendering)) or `undefined` 
-* `redirect`: Default redirection route. Defaults to 'list'
-* `refetch`: Function that allows you to refetch the record 
-* `resource`: Resource name deduced from the location. e.g. 'posts'
-* `save`: Update callback to be passed to the underlying form as submit handler
-* `saving`: Boolean, `true` when `dataProvider` is called to update the record
-* `error`: Error returned by `dataProvider` when it failed to fetch the record. Useful if you want to adapt the view instead of just showing a notification using the `onError` side effect.
+```jsx
+const {
+    defaultTitle, // Translated title based on the resource, e.g. 'Post #123'
+    isFetching, // Boolean, true while the record is being fetched, false once done fetching
+    isLoading, // Boolean, true until the record is available for the first time
+    mutationMode, // Mutation mode argument passed as parameter, or 'undoable' if not defined
+    record, // Either the record fetched via dataProvider.getOne() based on the id from the location, a cached version of the record (see also the Caching documentation page) or undefined 
+    redirect, // Default redirection route. Defaults to 'list'
+    refetch, // Function that allows you to refetch the record 
+    resource, // Resource name deduced from the location. e.g. 'posts'
+    save, // Update callback to be passed to the underlying form as submit handler
+    saving, // Boolean, true when dataProvider is called to update the record
+    error, // Error returned by dataProvider when it failed to fetch the record. Useful if you want to adapt the view instead of just showing a notification using the onError side effect.
+} = useEditController();
+```
+
diff --git a/docs/useList.md b/docs/useList.md
index b21afc00be9..47ea0d54604 100644
--- a/docs/useList.md
+++ b/docs/useList.md
@@ -258,44 +258,37 @@ const { data } = useList({
 
 `useList` returns an object with keys matching the shape of the `ListContext`: 
 
-**Data**
-
-* `data`: Array of the list records, e.g. `[{ id: 123, title: 'hello world' }, { ... }`
-* `total`: Total number of results for the current filters, excluding pagination. Useful to build the pagination controls, e.g. 23      
-* `isFetching`: Boolean, `true` while the data is being fetched, `false` once the data is fetched
-* `isLoading`: Boolean, `true` until the data is available for the first time
-
-**Pagination**
-
-* `page`: Current page. Starts at 1
-* `perPage`: Number of results per page. Defaults to 25
-* `setPage`: Callback to change the page, e.g. `setPage(3)`
-* `setPerPage`: Callback to change the number of results per page, e.g. `setPerPage(25)`
-* `hasPreviousPage`: Boolean, `true` if the current page is not the first one
-* `hasNextPage`: Boolean, `true` if the current page is not the last one
-
-**Sorting**
-
-* `sort`: Sort object `{ field, order }`, e.g. `{ field: 'date', order: 'DESC' }`
-* `setSort`: Callback to change the sort, e.g. `setSort({ field: 'name', order: 'ASC' })`
-
-**Filtering**
-
-* `filterValues`: Dictionary of filter values, e.g. `{ title: 'lorem', nationality: 'fr' }`
-* `displayedFilters`: Dictionary of displayed filters, e.g. `{ title: true, nationality: true }`
-* `setFilters`: Callback to update the filters, e.g. `setFilters(filters, displayedFilters)`
-* `showFilter`: Callback to show one of the filters, e.g. `showFilter('title', defaultValue)`
-* `hideFilter`: Callback to hide one of the filters, e.g. `hideFilter('title')`
-
-**Record selection**
-
-* `selectedIds`: Array listing the ids of the selected records, e.g. `[123, 456]`
-* `onSelect`: Callback to change the list of selected records, e.g. `onSelect([456, 789])`
-* `onToggleItem`: Callback to toggle the record selection for a given id, e.g. `onToggleItem(456)`
-* `onUnselectItems`: Callback to clear the record selection, e.g. `onUnselectItems();`
-
-**Misc**
-
-* `defaultTitle`: Translated title based on the resource, e.g. 'Posts'
-* `resource`: Resource name, deduced from the location. e.g. 'posts'
-* `refetch`: Callback for fetching the list data again
+```jsx
+const {
+    // Data
+    data, // Array of the list records, e.g. [{ id: 123, title: 'hello world' }, { ... }
+    total, // Total number of results for the current filters, excluding pagination. Useful to build the pagination controls, e.g. 23      
+    isFetching, // Boolean, true while the data is being fetched, false once the data is fetched
+    isLoading, // Boolean, true until the data is available for the first time
+    // Pagination
+    page, // Current page. Starts at 1
+    perPage, // Number of results per page. Defaults to 25
+    setPage, // Callback to change the page, e.g. setPage(3)
+    setPerPage, // Callback to change the number of results per page, e.g. setPerPage(25)
+    hasPreviousPage, // Boolean, true if the current page is not the first one
+    hasNextPage, // Boolean, true if the current page is not the last one
+    // Sorting
+    sort, // Sort object { field, order }, e.g. { field: 'date', order: 'DESC' }
+    setSort, // Callback to change the sort, e.g. setSort({ field: 'name', order: 'ASC' })
+    // Filtering
+    filterValues, // Dictionary of filter values, e.g. { title: 'lorem', nationality: 'fr' }
+    displayedFilters, // Dictionary of displayed filters, e.g. { title: true, nationality: true }
+    setFilters, // Callback to update the filters, e.g. setFilters(filters, displayedFilters)
+    showFilter, // Callback to show one of the filters, e.g. showFilter('title', defaultValue)
+    hideFilter, // Callback to hide one of the filters, e.g. hideFilter('title')
+    // Record selection
+    selectedIds, // Array listing the ids of the selected records, e.g. [123, 456]
+    onSelect, // Callback to change the list of selected records, e.g. onSelect([456, 789])
+    onToggleItem, // Callback to toggle the record selection for a given id, e.g. onToggleItem(456)
+    onUnselectItems, // Callback to clear the record selection, e.g. onUnselectItems();
+    // Misc
+    defaultTitle, // Translated title based on the resource, e.g. 'Posts'
+    resource, // Resource name, deduced from the location. e.g. 'posts'
+    refetch, // Callback for fetching the list data again
+} = useList();
+```
diff --git a/docs/useListController.md b/docs/useListController.md
index a7d9c68f828..3f4a567dc3c 100644
--- a/docs/useListController.md
+++ b/docs/useListController.md
@@ -143,44 +143,37 @@ You can disable this feature by setting the `storeKey` prop to `false`. When dis
 
 `useListController` returns an object with the following keys: 
 
-**Data**
-
-* `data`: Array of the list records, e.g. `[{ id: 123, title: 'hello world' }, { ... }`
-* `total`: Total number of results for the current filters, excluding pagination. Useful to build the pagination controls, e.g. 23      
-* `isFetching`: Boolean, `true` while the data is being fetched, `false` once the data is fetched
-* `isLoading`: Boolean, `true` until the data is available for the first time
-
-**Pagination**
-
-* `page`: Current page. Starts at 1
-* `perPage`: Number of results per page. Defaults to 25
-* `setPage`: Callback to change the page, e.g. `setPage(3)`
-* `setPerPage`: Callback to change the number of results per page, e.g. `setPerPage(25)`
-* `hasPreviousPage`: Boolean, `true` if the current page is not the first one
-* `hasNextPage`: Boolean, `true` if the current page is not the last one
-
-**Sorting**
-
-* `sort`: Sort object `{ field, order }`, e.g. `{ field: 'date', order: 'DESC' }`
-* `setSort`: Callback to change the sort, e.g. `setSort({ field: 'name', order: 'ASC' })`
-
-**Filtering**
-
-* `filterValues`: Dictionary of filter values, e.g. `{ title: 'lorem', nationality: 'fr' }`
-* `displayedFilters`: Dictionary of displayed filters, e.g. `{ title: true, nationality: true }`
-* `setFilters`: Callback to update the filters, e.g. `setFilters(filters, displayedFilters)`
-* `showFilter`: Callback to show one of the filters, e.g. `showFilter('title', defaultValue)`
-* `hideFilter`: Callback to hide one of the filters, e.g. `hideFilter('title')`
-
-**Record selection**
-
-* `selectedIds`: Array listing the ids of the selected records, e.g. `[123, 456]`
-* `onSelect`: Callback to change the list of selected records, e.g. `onSelect([456, 789])`
-* `onToggleItem`: Callback to toggle the record selection for a given id, e.g. `onToggleItem(456)`
-* `onUnselectItems`: Callback to clear the record selection, e.g. `onUnselectItems();`
-
-**Misc**
-
-* `defaultTitle`: Translated title based on the resource, e.g. 'Posts'
-* `resource`: Resource name, deduced from the location. e.g. 'posts'
-* `refetch`: Callback for fetching the list data again
+```jsx
+const {
+    // Data
+    data, // Array of the list records, e.g. [{ id: 123, title: 'hello world' }, { ... }
+    total, // Total number of results for the current filters, excluding pagination. Useful to build the pagination controls, e.g. 23      
+    isFetching, // Boolean, true while the data is being fetched, false once the data is fetched
+    isLoading, // Boolean, true until the data is available for the first time
+    // Pagination
+    page, // Current page. Starts at 1
+    perPage, // Number of results per page. Defaults to 25
+    setPage, // Callback to change the page, e.g. setPage(3)
+    setPerPage, // Callback to change the number of results per page, e.g. setPerPage(25)
+    hasPreviousPage, // Boolean, true if the current page is not the first one
+    hasNextPage, // Boolean, true if the current page is not the last one
+    // Sorting
+    sort, // Sort object { field, order }, e.g. { field: 'date', order: 'DESC' }
+    setSort, // Callback to change the sort, e.g. setSort({ field: 'name', order: 'ASC' })
+    // Filtering
+    filterValues, // Dictionary of filter values, e.g. { title: 'lorem', nationality: 'fr' }
+    displayedFilters, // Dictionary of displayed filters, e.g. { title: true, nationality: true }
+    setFilters, // Callback to update the filters, e.g. setFilters(filters, displayedFilters)
+    showFilter, // Callback to show one of the filters, e.g. showFilter('title', defaultValue)
+    hideFilter, // Callback to hide one of the filters, e.g. hideFilter('title')
+    // Record selection
+    selectedIds, // Array listing the ids of the selected records, e.g. [123, 456]
+    onSelect, // Callback to change the list of selected records, e.g. onSelect([456, 789])
+    onToggleItem, // Callback to toggle the record selection for a given id, e.g. onToggleItem(456)
+    onUnselectItems, // Callback to clear the record selection, e.g. onUnselectItems();
+    // Misc
+    defaultTitle, // Translated title based on the resource, e.g. 'Posts'
+    resource, // Resource name, deduced from the location. e.g. 'posts'
+    refetch, // Callback for fetching the list data again
+} = useListController();
+```
diff --git a/docs/useSaveContext.md b/docs/useSaveContext.md
index e88931f858c..b8f1761eb1e 100644
--- a/docs/useSaveContext.md
+++ b/docs/useSaveContext.md
@@ -42,6 +42,10 @@ const MyComponent = () => {
 
 `useSaveContext` returns an object with the following keys:
 
-* `save`: Create or update callback which receives form data and calls `dataProvider`
-* `saving`: Boolean, `true` when `dataProvider` is called
-* `mutationMode`: Current mutation mode, either 'undoable', 'optimistic' or 'pessimistic'
+```jsx
+const {
+    save, // Create or update callback which receives form data and calls dataProvider
+    saving, // Boolean, true when dataProvider is called
+    mutationMode, // Current mutation mode, either 'undoable', 'optimistic' or 'pessimistic'
+} = useSaveContext();
+```
diff --git a/docs/useShowContext.md b/docs/useShowContext.md
index e0db8430c75..7a7c1128477 100644
--- a/docs/useShowContext.md
+++ b/docs/useShowContext.md
@@ -47,14 +47,17 @@ const PostShow = () => (
 
 `useShowContext` returns an object with the same keys as [`useShowController`](./useShowController.md):
 
-* `defaultTitle`: Translated title based on the resource, e.g. 'Post #123'
-* `isFetching`: Boolean, `true` while the record is being fetched, and false once done fetching
-* `isLoading`: Boolean, `true` until the record is available for the first time
-* `record`: Either the record fetched via `dataProvider.getOne()` based on the id from the location, a cached version of the record (see also [Caching](./Caching.md#optimistic-rendering)) or `undefined` 
-* `refetch`: Callback to refetch the record via `dataProvider.getOne()`
-* `resource`: The resource name, deduced from the location. e.g. 'posts'
-* `error`: Error returned by dataProvider when it failed to fetch the record. Useful if you want to adapt the view instead of just showing a notification using the `onError` side effect.
-
+```jsx
+const {
+    defaultTitle, // Translated title based on the resource, e.g. 'Post #123'
+    isFetching, // Boolean, true while the record is being fetched, and false once done fetching
+    isLoading, // Boolean, true until the record is available for the first time
+    record, // Either the record fetched via dataProvider.getOne() based on the id from the location, a cached version of the record (see also the Caching documentation page) or undefined 
+    refetch, // Callback to refetch the record via dataProvider.getOne()
+    resource, // The resource name, deduced from the location. e.g. 'posts'
+    error, // Error returned by dataProvider when it failed to fetch the record. Useful if you want to adapt the view instead of just showing a notification using the onError side effect.
+} = useShowContext();
+```
 
 ## TypeScript
 
diff --git a/docs/useShowController.md b/docs/useShowController.md
index b8be2360146..0b6e1de2d32 100644
--- a/docs/useShowController.md
+++ b/docs/useShowController.md
@@ -170,13 +170,17 @@ const PostShow = () => {
 
 `useShowController` returns an object with the following keys:
 
-* `defaultTitle`: Translated title based on the resource, e.g. 'Post #123'
-* `isFetching`: Boolean, `true` while the record is being fetched, and false once done fetching
-* `isLoading`: Boolean, `true` until the record is available for the first time
-* `record`: Either the record fetched via `dataProvider.getOne()` based on the id from the location, a cached version of the record (see also [Caching](./Caching.md#optimistic-rendering)) or `undefined` 
-* `refetch`: Callback to refetch the record via `dataProvider.getOne()`
-* `resource`: The resource name, deduced from the location. e.g. 'posts'
-* `error`: Error returned by dataProvider when it failed to fetch the record. Useful if you want to adapt the view instead of just showing a notification using the `onError` side effect.
+```jsx
+const {
+    defaultTitle, // Translated title based on the resource, e.g. 'Post #123'
+    isFetching, // Boolean, true while the record is being fetched, and false once done fetching
+    isLoading, // Boolean, true until the record is available for the first time
+    record, // Either the record fetched via dataProvider.getOne() based on the id from the location, a cached version of the record (see also the Caching documentation page) or undefined 
+    refetch, // Callback to refetch the record via dataProvider.getOne()
+    resource, // The resource name, deduced from the location. e.g. 'posts'
+    error, // Error returned by dataProvider when it failed to fetch the record. Useful if you want to adapt the view instead of just showing a notification using the onError side effect.
+} = useShowController();
+```
 
 ## Controlled Mode
 

From 2b7fcfc07bcfd3583334a6eef420f903293598b0 Mon Sep 17 00:00:00 2001
From: sebashwa <sebastian@priorist.com>
Date: Tue, 5 Dec 2023 23:06:43 +0100
Subject: [PATCH 6/6] Revert documentation style for useListContext

---
 docs/useListContext.md | 75 +++++++++++++++++++-----------------------
 1 file changed, 34 insertions(+), 41 deletions(-)

diff --git a/docs/useListContext.md b/docs/useListContext.md
index 88e913a50e6..02b95849921 100644
--- a/docs/useListContext.md
+++ b/docs/useListContext.md
@@ -58,47 +58,40 @@ export const PostList = () => (
 
 `useListContext` returns an object with the following keys:
 
-**Data**
-
-* `data`: Array of the list records, e.g. `[{ id: 123, title: 'hello world' }, { ... }`
-* `total`: Total number of results for the current filters, excluding pagination. Useful to build the pagination controls, e.g. 23      
-* `isFetching`: Boolean, `true` while the data is being fetched, `false` once the data is fetched
-* `isLoading`: Boolean, `true` until the data is available for the first time
-
-**Pagination**
-
-* `page`: Current page. Starts at 1
-* `perPage`: Number of results per page. Defaults to 25
-* `setPage`: Callback to change the page, e.g. `setPage(3)`
-* `setPerPage`: Callback to change the number of results per page, e.g. `setPerPage(25)`
-* `hasPreviousPage`: Boolean, `true` if the current page is not the first one
-* `hasNextPage`: Boolean, `true` if the current page is not the last one
-
-**Sorting**
-
-* `sort`: Sort object `{ field, order }`, e.g. `{ field: 'date', order: 'DESC' }`
-* `setSort`: Callback to change the sort, e.g. `setSort({ field: 'name', order: 'ASC' })`
-
-**Filtering**
-
-* `filterValues`: Dictionary of filter values, e.g. `{ title: 'lorem', nationality: 'fr' }`
-* `displayedFilters`: Dictionary of displayed filters, e.g. `{ title: true, nationality: true }`
-* `setFilters`: Callback to update the filters, e.g. `setFilters(filters, displayedFilters)`
-* `showFilter`: Callback to show one of the filters, e.g. `showFilter('title', defaultValue)`
-* `hideFilter`: Callback to hide one of the filters, e.g. `hideFilter('title')`
-
-**Record selection**
-
-* `selectedIds`: Array listing the ids of the selected records, e.g. `[123, 456]`
-* `onSelect`: Callback to change the list of selected records, e.g. `onSelect([456, 789])`
-* `onToggleItem`: Callback to toggle the record selection for a given id, e.g. `onToggleItem(456)`
-* `onUnselectItems`: Callback to clear the record selection, e.g. `onUnselectItems();`
-
-**Misc**
-
-* `defaultTitle`: Translated title based on the resource, e.g. 'Posts'
-* `resource`: Resource name, deduced from the location. e.g. 'posts'
-* `refetch`: Callback for fetching the list data again
+```jsx
+const {
+    // Data
+    data, // Array of the list records, e.g. [{ id: 123, title: 'hello world' }, { ... }
+    total, // Total number of results for the current filters, excluding pagination. Useful to build the pagination controls, e.g. 23      
+    isFetching, // Boolean, true while the data is being fetched, false once the data is fetched
+    isLoading, // Boolean, true until the data is available for the first time
+    // Pagination
+    page, // Current page. Starts at 1
+    perPage, // Number of results per page. Defaults to 25
+    setPage, // Callback to change the page, e.g. setPage(3)
+    setPerPage, // Callback to change the number of results per page, e.g. setPerPage(25)
+    hasPreviousPage, // Boolean, true if the current page is not the first one
+    hasNextPage, // Boolean, true if the current page is not the last one
+    // Sorting
+    sort, // Sort object { field, order }, e.g. { field: 'date', order: 'DESC' }
+    setSort, // Callback to change the sort, e.g. setSort({ field: 'name', order: 'ASC' })
+    // Filtering
+    filterValues, // Dictionary of filter values, e.g. { title: 'lorem', nationality: 'fr' }
+    displayedFilters, // Dictionary of displayed filters, e.g. { title: true, nationality: true }
+    setFilters, // Callback to update the filters, e.g. setFilters(filters, displayedFilters)
+    showFilter, // Callback to show one of the filters, e.g. showFilter('title', defaultValue)
+    hideFilter, // Callback to hide one of the filters, e.g. hideFilter('title')
+    // Record selection
+    selectedIds, // Array listing the ids of the selected records, e.g. [123, 456]
+    onSelect, // Callback to change the list of selected records, e.g. onSelect([456, 789])
+    onToggleItem, // Callback to toggle the record selection for a given id, e.g. onToggleItem(456)
+    onUnselectItems, // Callback to clear the record selection, e.g. onUnselectItems();
+    // Misc
+    defaultTitle, // Translated title based on the resource, e.g. 'Posts'
+    resource, // Resource name, deduced from the location. e.g. 'posts'
+    refetch, // Callback for fetching the list data again
+} = useListContext();
+```
 
 ## Declarative Version