[Doc] Update the hooks documentation for consistent TOC #9453

sebashwa · 2023-11-16T23:23:31Z

Records returned from a context / controller hook are sometimes undefined or a cached version of the record. This is now stated more explicitly in the hook documentations for hooks that return the record from a context.

Things changed:

Had to move some documentation out of code blocks to add those links to the caching page.
Tried to make the documentation for the list / edit / create / show hooks more consistent (added headings / using the same documentation format for Arguments / Return Value).
Added "Props"-Headings for some more components to pop up in the navigation

Related to #9451

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.

fzaninotto

Nice! Although I don't agree with all your proposed changes.

fzaninotto · 2023-11-17T06:30:13Z

docs/useCreateContext.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();
-```


I prefer the previous version

fzaninotto · 2023-11-17T06:30:42Z

docs/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
-} = useCreateController();
-```


I prefer this version

fzaninotto · 2023-11-17T06:30:55Z

docs/useEditContext.md

-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();
-```


fzaninotto · 2023-11-17T06:33:25Z

docs/useEditController.md

+
+`useEditController` returns an object with the following keys:
+
+* `defaultTitle`: Translated title based on the resource, e.g. 'Post #123'


keep the object format

fzaninotto · 2023-11-17T06:33:46Z

docs/useList.md


-```jsx


and the object syntax

fzaninotto · 2023-11-17T06:34:30Z

docs/useListController.md

@@ -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:


PLease keep the object format

fzaninotto · 2023-11-17T06:35:26Z

docs/useSaveContext.md

+
+`useSaveContext` returns an object with the following keys:
+
+* `save`: Create or update callback which receives form data and calls `dataProvider`


MAke it a code snippet

fzaninotto · 2023-11-17T06:35:58Z

docs/useShowContext.md

+
+`useShowContext` returns an object with the same keys as [`useShowController`](./useShowController.md):
+
+* `defaultTitle`: Translated title based on the resource, e.g. 'Post #123'


fzaninotto · 2023-11-17T06:36:28Z

docs/useShowController.md

+
+`useShowController` returns an object with the following keys:
+
+* `defaultTitle`: Translated title based on the resource, e.g. 'Post #123'


Please use an object in a code snippet

fzaninotto · 2023-11-17T06:39:19Z

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


We use Parameters in most hooks. Why is Arguments better? And if you change it here, you must change it everywhere.

Wasn't sure what's the preference, both work for me. Will change it back soon!

sebashwa · 2023-11-17T07:30:55Z

Hey @fzaninotto,

thanks for your feedback. My intention to use the listing instead of the object syntax in a codeblock were:

It's more consistent with the documentation for parameters (which are listings in most of the places, although sometimes also tables in case types / default values are documented). I don't see why the return value should be documented differently from the parameters.
It's not necessary to scroll to the right to read the descriptions of the object keys (at least I have to, maybe it's a resolution thing)
I thought it's not possible to put links inside codeblocks and I wanted to link to the "Caching" page for the returned record key. This was the main reason why I abandoned the codeblocks, although I think now, that's actually not true.

If you still think I should switch back to codeblocks, I will of course do so but imho I think it's neither more readable nor consistent with the rest of the documentation. What do you think?

fzaninotto · 2023-11-17T08:44:32Z

I hear your arguments, yet I prefer the code snippet for the return values.

fzaninotto · 2023-11-29T17:12:36Z

Any updates?

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.

sebashwa · 2023-12-05T21:50:14Z

Any updates?

Wasn't able to add those changes earlier.
I reverted to the code block documentation style, although it's now no longer possible to link to the Caching page from within the code block. So it just remains a hint to the Caching page for now.

fzaninotto · 2023-12-19T10:53:33Z

Thanks!

Add props headings for some components

3d1635f

vercel bot deployed to Preview – react-admin-storybook November 16, 2023 23:27 View deployment

sebashwa force-pushed the doc-link-to-caching-page branch from e7c47a5 to 7690839 Compare November 16, 2023 23:33

sebashwa added 2 commits November 17, 2023 00:35

Use more consistent documentation style for hooks

a3f9567

sebashwa force-pushed the doc-link-to-caching-page branch from 7690839 to a786c30 Compare November 16, 2023 23:35

vercel bot deployed to Preview – react-admin-storybook November 16, 2023 23:38 View deployment

fzaninotto requested changes Nov 17, 2023

View reviewed changes

sebashwa added 2 commits December 5, 2023 22:20

Rename arguments headings to parameters

dd4aa48

Revert documentation style changes

a8dfbe9

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.

vercel bot deployed to Preview – react-admin-storybook December 5, 2023 21:48 View deployment

Merge branch 'master' into doc-link-to-caching-page

70dbfd6

vercel bot deployed to Preview – react-admin-storybook December 5, 2023 22:06 View deployment

Revert documentation style for useListContext

2b7fcfc

vercel bot deployed to Preview – react-admin-storybook December 5, 2023 22:10 View deployment

fzaninotto approved these changes Dec 19, 2023

View reviewed changes

fzaninotto merged commit 8599362 into marmelab:master Dec 19, 2023

fzaninotto added this to the 4.16.4 milestone Dec 19, 2023

fzaninotto changed the title ~~Link to caching documentation page for hooks returning records~~ [Doc] Update the hooks documentation for consistent TOC Dec 19, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Doc] Update the hooks documentation for consistent TOC #9453

[Doc] Update the hooks documentation for consistent TOC #9453

sebashwa commented Nov 16, 2023 •

edited

Loading

fzaninotto left a comment

fzaninotto Nov 17, 2023

fzaninotto Nov 17, 2023

fzaninotto Nov 17, 2023

fzaninotto Nov 17, 2023

fzaninotto Nov 17, 2023

fzaninotto Nov 17, 2023

fzaninotto Nov 17, 2023

fzaninotto Nov 17, 2023

fzaninotto Nov 17, 2023

fzaninotto Nov 17, 2023

sebashwa Nov 17, 2023

sebashwa commented Nov 17, 2023 •

edited

Loading

fzaninotto commented Nov 17, 2023

fzaninotto commented Nov 29, 2023

sebashwa commented Dec 5, 2023

fzaninotto commented Dec 19, 2023


		`useEditController` returns an object with the following keys:

		* `defaultTitle`: Translated title based on the resource, e.g. 'Post #123'

		@@ -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:


		`useSaveContext` returns an object with the following keys:

		* `save`: Create or update callback which receives form data and calls `dataProvider`


		`useShowContext` returns an object with the same keys as [`useShowController`](./useShowController.md):

		* `defaultTitle`: Translated title based on the resource, e.g. 'Post #123'


		`useShowController` returns an object with the following keys:

		* `defaultTitle`: Translated title based on the resource, e.g. 'Post #123'


		```jsx

[Doc] Update the hooks documentation for consistent TOC #9453

[Doc] Update the hooks documentation for consistent TOC #9453

Conversation

sebashwa commented Nov 16, 2023 • edited Loading

fzaninotto left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sebashwa commented Nov 17, 2023 • edited Loading

fzaninotto commented Nov 17, 2023

fzaninotto commented Nov 29, 2023

sebashwa commented Dec 5, 2023

fzaninotto commented Dec 19, 2023

sebashwa commented Nov 16, 2023 •

edited

Loading

sebashwa commented Nov 17, 2023 •

edited

Loading