Add documentation for the EditorProvider and ExperimentalEditorProvid…

…er components (WordPress#61739) * Add documentation for the EditorProvider and ExperimentalEditorProvider components * Address ESLint warning react-hooks/exhaustive-deps * Refine EditorProvider editor component JSDocs * Auto-generate EditorProvider editor docs * Revert "Address ESLint warning react-hooks/exhaustive-deps" This reverts commit 3f15d73. --------- Co-authored-by: Damon Cook <damonacook@gmail.com>
carstingaxion · Jun 4, 2024 · 0fa6e68 · 0fa6e68
1 parent b366002
commit 0fa6e68
Show file tree

Hide file tree

Showing 3 changed files with 91 additions and 38 deletions.
diff --git a/packages/editor/README.md b/packages/editor/README.md
@@ -350,7 +350,35 @@ _Returns_
 
 ### EditorProvider
 
-Undocumented declaration.
+This component establishes a new post editing context, and serves as the entry point for a new post editor (or post with template editor).
+
+It supports a large number of post types, including post, page, templates, custom post types, patterns, template parts.
+
+All modification and changes are performed to the `@wordpress/core-data` store.
+
+_Usage_
+
+```jsx
+<EditorProvider
+	post={ post }
+	settings={ settings }
+	__unstableTemplate={ template }
+>
+	{ children }
+</EditorProvider>
+```
+
+_Parameters_
+
+-   _props_ `Object`: The component props.
+-   _props.post_ `[Object]`: The post object to edit. This is required.
+-   _props.\_\_unstableTemplate_ `[Object]`: The template object wrapper the edited post. This is optional and can only be used when the post type supports templates (like posts and pages).
+-   _props.settings_ `[Object]`: The settings object to use for the editor. This is optional and can be used to override the default settings.
+-   _props.children_ `[Element]`: Children elements for which the BlockEditorProvider context should apply. This is optional.
+
+_Returns_
+
+-   `JSX.Element`: The rendered EditorProvider component.
 
 ### EditorSnackbars
 

diff --git a/packages/editor/src/components/provider/README.md b/packages/editor/src/components/provider/README.md
diff --git a/packages/editor/src/components/provider/index.js b/packages/editor/src/components/provider/index.js
@@ -59,6 +59,12 @@ const NON_CONTEXTUAL_POST_TYPES = [
  * @param {Array}   post     Block list.
  * @param {boolean} template Whether the page content has focus (and the surrounding template is inert). If `true` return page content blocks. Default `false`.
  * @param {string}  mode     Rendering mode.
+ *
+ * @example
+ * ```jsx
+ * const [ blocks, onInput, onChange ] = useBlockEditorProps( post, template, mode );
+ * ```
+ *
  * @return {Array} Block editor props.
  */
 function useBlockEditorProps( post, template, mode ) {
@@ -118,6 +124,32 @@ function useBlockEditorProps( post, template, mode ) {
 	];
 }
 
+/**
+ * This component provides the editor context and manages the state of the block editor.
+ *
+ * @param {Object}  props                                The component props.
+ * @param {Object}  props.post                           The post object.
+ * @param {Object}  props.settings                       The editor settings.
+ * @param {boolean} props.recovery                       Indicates if the editor is in recovery mode.
+ * @param {Array}   props.initialEdits                   The initial edits for the editor.
+ * @param {Object}  props.children                       The child components.
+ * @param {Object}  [props.BlockEditorProviderComponent] The block editor provider component to use. Defaults to ExperimentalBlockEditorProvider.
+ * @param {Object}  [props.__unstableTemplate]           The template object.
+ *
+ * @example
+ * ```jsx
+ * <ExperimentalEditorProvider
+ *   post={ post }
+ *   settings={ settings }
+ *   recovery={ recovery }
+ *   initialEdits={ initialEdits }
+ *   __unstableTemplate={ template }
+ * >
+ *   { children }
+ * </ExperimentalEditorProvider>
+ *
+ * @return {Object} The rendered ExperimentalEditorProvider component.
+ */
 export const ExperimentalEditorProvider = withRegistryProvider(
 	( {
 		post,
@@ -293,6 +325,36 @@ export const ExperimentalEditorProvider = withRegistryProvider(
 	}
 );
 
+/**
+ * This component establishes a new post editing context, and serves as the entry point for a new post editor (or post with template editor).
+ *
+ * It supports a large number of post types, including post, page, templates,
+ * custom post types, patterns, template parts.
+ *
+ * All modification and changes are performed to the `@wordpress/core-data` store.
+ *
+ * @param {Object}  props                      The component props.
+ * @param {Object}  [props.post]               The post object to edit. This is required.
+ * @param {Object}  [props.__unstableTemplate] The template object wrapper the edited post.
+ *                                             This is optional and can only be used when the post type supports templates (like posts and pages).
+ * @param {Object}  [props.settings]           The settings object to use for the editor.
+ *                                             This is optional and can be used to override the default settings.
+ * @param {Element} [props.children]           Children elements for which the BlockEditorProvider context should apply.
+ *                                             This is optional.
+ *
+ * @example
+ * ```jsx
+ * <EditorProvider
+ *   post={ post }
+ *   settings={ settings }
+ *   __unstableTemplate={ template }
+ * >
+ *   { children }
+ * </EditorProvider>
+ * ```
+ *
+ * @return {JSX.Element} The rendered EditorProvider component.
+ */
 export function EditorProvider( props ) {
 	return (
 		<ExperimentalEditorProvider