update doc and jsdoc

Author: slax57

docs/AppBar.md

@@ -64,7 +64,6 @@ const App = () => (
 
 | Prop                | Required | Type           | Default  | Description                                         |
 | ------------------- | -------- | -------------- | -------- | --------------------------------------------------- |
-| `alwaysOn`          | Optional | `boolean`      | -        | When true, the app bar is always visible            |
 | `children`          | Optional | `ReactElement` | -        | What to display in the central part of the app bar  |
 | `color`             | Optional | `string`       | -        | The background color of the app bar                 |
 | `sx`                | Optional | `SxProps`      | -        | Style overrides, powered by MUI System              |
@@ -73,17 +72,6 @@ const App = () => (
 
 Additional props are passed to [the underlying MUI `<AppBar>` element](https://mui.com/material-ui/api/app-bar/).
 
-## `alwaysOn`
-
-By default, the app bar is hidden when the user scrolls down the page. This is useful to save space on small screens. But if you want to keep the app bar always visible, you can set the `alwaysOn` prop to `true`.
-
-```jsx
-// in src/MyAppBar.js
-import { AppBar } from 'react-admin';
-
-const MyAppBar = () => <AppBar alwaysOn />;
-```
-
 ## `children`
 
 The `<AppBar>` component accepts a `children` prop, which is displayed in the central part of the app bar. This is useful to add buttons to the app bar, for instance, a light/dark theme switcher.

docs/Layout.md

@@ -45,14 +45,15 @@ const App = () => (
 
 ## Props
 
-| Prop        | Required | Type        | Default  | Description                                                           |
-| ----------- | -------- | ----------- | -------- | --------------------------------------------------------------------- |
-| `appBar`    | Optional | `Component` | -        | A React component rendered at the top of the layout                   |
-| `className` | Optional | `string`    | -        | Passed to the root `<div>` component                                  |
-| `error`     | Optional | `Component` | -        | A React component rendered in the content area in case of error       |
-| `menu`      | Optional | `Component` | -        | A React component rendered at the side of the screen                  |
-| `sidebar`   | Optional | `Component` | -        | A React component responsible for rendering the menu (e.g. in a drawer) |
-| `sx`        | Optional | `SxProps`   | -        | Style overrides, powered by MUI System                                |
+| Prop             | Required | Type        | Default  | Description                                                             |
+| ---------------- | -------- | ----------- | -------- | ----------------------------------------------------------------------- |
+| `appBar`         | Optional | `Component` | -        | A React component rendered at the top of the layout                     |
+| `appBarAlwaysOn` | Optional | `boolean`   | -        | When true, the app bar is always visible                                |
+| `className`      | Optional | `string`    | -        | Passed to the root `<div>` component                                    |
+| `error`          | Optional | `Component` | -        | A React component rendered in the content area in case of error         |
+| `menu`           | Optional | `Component` | -        | A React component rendered at the side of the screen                    |
+| `sidebar`        | Optional | `Component` | -        | A React component responsible for rendering the menu (e.g. in a drawer) |
+| `sx`             | Optional | `SxProps`   | -        | Style overrides, powered by MUI System                                  |
 
 React-admin injects more props at runtime based on the `<Admin>` props:
 
@@ -115,6 +116,18 @@ export const MyAppBar = () => (
 
 Check out the [`<AppBar>` documentation](./AppBar.md) for more information, and for instructions on building your own AppBar.
 
+## `appBarAlwaysOn`
+
+By default, the app bar is hidden when the user scrolls down the page. This is useful to save space on small screens. But if you want to keep the app bar always visible, you can set the `appBarAlwaysOn` prop to `true`.
+
+```jsx
+// in src/MyLayout.js
+import * as React from 'react';
+import { Layout } from 'react-admin';
+
+export const MyLayout = (props) => <Layout {...props} appBarAlwaysOn />;
+```
+
 ## `className`
 
 `className` is passed to the root `<div>` component. It lets you style the layout with CSS - but the `sx` prop is preferred.

packages/ra-ui-materialui/src/layout/AppBar.tsx

@@ -126,6 +126,11 @@ AppBar.propTypes = {
 const DefaultUserMenu = <UserMenu />;
 
 export interface AppBarProps extends Omit<MuiAppBarProps, 'title'> {
+    /**
+     * This prop is injected by Layout. You should not use it directly unless
+     * you are using a custom layout.
+     * If you are using the default layout, use `<Layout appBarAlwaysOn>` instead.
+     */
     alwaysOn?: boolean;
     container?: React.ElementType<any>;
     /**