diff --git a/docs/Authentication.md b/docs/Authentication.md
index 7ce29316636..530f72e0ac0 100644
--- a/docs/Authentication.md
+++ b/docs/Authentication.md
@@ -398,7 +398,7 @@ To avoid rendering a component and force waiting for the `authProvider` response
 
 - `loading`: `true` just after mount, while the `authProvider` is being called. `false` once the `authProvider` has answered.
 - `loaded`: the opposite of `loading`.
-- `authenticated`: `undefined` while loading. then `true` or `false` depending on the `authProvider` response.
+- `authenticated`: `true` while loading. then `true` or `false` depending on the `authProvider` response.
 
 You can render different content depending on the authenticated status. 
 
diff --git a/packages/ra-core/src/auth/useAuthState.ts b/packages/ra-core/src/auth/useAuthState.ts
index c54fe1b7d77..6e25e272a2e 100644
--- a/packages/ra-core/src/auth/useAuthState.ts
+++ b/packages/ra-core/src/auth/useAuthState.ts
@@ -12,20 +12,20 @@ interface State {
 const emptyParams = {};
 
 /**
- * Hook for getting the authentication status and restricting access to authenticated users
+ * Hook for getting the authentication status
  *
  * Calls the authProvider.checkAuth() method asynchronously.
- * If the authProvider returns a rejected promise, logs the user out.
  *
  * The return value updates according to the authProvider request state:
  *
- * - start:   { authenticated: false, loading: true, loaded: false }
- * - success: { authenticated: true,  loading: false, loaded: true }
- * - error:   { authenticated: false, loading: false, loaded: true }
+ * - loading: true just after mount, while the authProvider is being called. false once the authProvider has answered.
+ * - loaded: the opposite of loading.
+ * - authenticated: true while loading. then true or false depending on the authProvider response.
  *
- * Useful in custom page components that can work both for connected and
- * anonymous users. For pages that can only work for connected users,
- * prefer the useAuthenticated() hook.
+ * To avoid rendering a component and force waiting for the authProvider response, use the useAuthState() hook
+ * instead of the useAuthenticated() hook.
+ *
+ * You can render different content depending on the authenticated status.
  *
  * @see useAuthenticated()
  *
@@ -34,19 +34,18 @@ const emptyParams = {};
  * @returns The current auth check state. Destructure as { authenticated, error, loading, loaded }.
  *
  * @example
- *     import { useAuthState } from 'react-admin';
+ * import { useAuthState, Loading } from 'react-admin';
  *
- *     const CustomRoutes = [
- *         <Route path="/bar" render={() => {
- *              const { authenticated } = useAuthState({ myContext: 'foobar' });
- *              return authenticated ? <Bar /> : <BarNotAuthenticated />;
- *          }} />,
- *     ];
- *     const App = () => (
- *         <Admin customRoutes={customRoutes}>
- *             ...
- *         </Admin>
- *     );
+ * const MyPage = () => {
+ *     const { loading, authenticated } = useAuthState();
+ *     if (loading) {
+ *         return <Loading />;
+ *     }
+ *     if (authenticated) {
+ *        return <AuthenticatedContent />;
+ *     }
+ *     return <AnonymousContent />;
+ * };
  */
 const useAuthState = (params: any = emptyParams): State => {
     const [state, setState] = useSafeSetState({
diff --git a/packages/ra-core/src/auth/useCheckAuth.ts b/packages/ra-core/src/auth/useCheckAuth.ts
index ab7ffcc98e2..8ca1717b118 100644
--- a/packages/ra-core/src/auth/useCheckAuth.ts
+++ b/packages/ra-core/src/auth/useCheckAuth.ts
@@ -10,7 +10,7 @@ import useNotify from '../sideEffect/useNotify';
  * and throws an error.
  *
  * This is a low level hook. See those more specialized hooks
- * for common authentication tasks, based on useAuthCheck.
+ * for common authentication tasks, based on useCheckAuth.
  *
  * @see useAuthenticated
  * @see useAuthState