Improve documentation

Author: fzaninotto

packages/ra-core/src/controller/field/ArrayFieldBase.tsx

@@ -15,21 +15,15 @@ import type { BaseFieldProps } from './types';
  *
  * @example
  * const PostShow = () => (
- *    <Show>
- *       <SimpleShowLayout>
- *           <ArrayFieldBase source="tags">
- *               <WithListContext
- *                   render={({ data }) => (
- *                       <ul>
- *                           {data.map(tag => (
- *                               <li key={tag.name}>{tag.name}</li>
- *                           ))}
- *                       </ul>
- *                   )}
- *               />
- *           </ArrayFieldBase>
- *      </SimpleShowLayout>
- *   </Show>
+ *    <ShowBase>
+ *       <ArrayFieldBase source="tags">
+ *          <ul>
+ *              <RecordsIterator
+ *                  render={record => <li key={record.id}>{record.name}</li>}
+ *              />
+ *          </ul>
+ *       </ArrayFieldBase>
+ *   </ShowBase>
  * );
  *
  * @see useListContext

packages/ra-ui-materialui/src/field/ArrayField.stories.tsx

@@ -8,6 +8,7 @@ import {
     TestMemoryRouter,
     ResourceContextProvider,
     downloadCSV,
+    RecordsIterator,
 } from 'ra-core';
 import polyglotI18nProvider from 'ra-i18n-polyglot';
 import englishMessages from 'ra-language-english';
@@ -42,6 +43,18 @@ export const Basic = () => (
     </TestMemoryRouter>
 );
 
+export const WithRecordsIterator = () => (
+    <TestMemoryRouter>
+        <ArrayField record={{ id: 123, books }} source="books">
+            <ul>
+                <RecordsIterator
+                    render={record => <li key={record.id}>{record.title}</li>}
+                />
+            </ul>
+        </ArrayField>
+    </TestMemoryRouter>
+);
+
 const i18nProvider = polyglotI18nProvider(() => englishMessages);
 
 export const PerPage = () => (

packages/ra-ui-materialui/src/field/ArrayField.tsx

@@ -2,6 +2,27 @@ import { ArrayFieldBase, type ArrayFieldBaseProps } from 'ra-core';
 
 import type { FieldProps } from './types';
 
+/**
+ * Renders an embedded array of objects.
+ *
+ * ArrayField creates a ListContext with the field value, and renders its
+ * children components - usually iterator components.
+ *
+ * @example
+ * const PostShow = () => (
+ *    <Show>
+ *       <SimpleShowLayout>
+ *           <ArrayField source="tags">
+ *              <SingleFieldList>
+ *                 <ChipField source="name" />
+ *             </SingleFieldList>
+ *           </ArrayField>
+ *      </SimpleShowLayout>
+ *   </Show>
+ * );
+ *
+ * @see useListContext
+ */
 export const ArrayField = ArrayFieldBase;
 
 export interface ArrayFieldProps<