plugins: set up auto-generated API docs (#14263)

WordPress · Mar 20, 2019 · 6e2e8d8 · 6e2e8d8
1 parent 76e5dac
commit 6e2e8d8
Show file tree

Hide file tree

Showing 4 changed files with 217 additions and 60 deletions.
diff --git a/bin/update-readmes.js b/bin/update-readmes.js
@@ -25,7 +25,7 @@ const packages = [
 	'html-entities',
 	'i18n',
 	'keycodes',
-	//'plugins',
+	'plugins',
 	'priority-queue',
 	'redux-routine',
 	'rich-text',

diff --git a/packages/plugins/README.md b/packages/plugins/README.md
@@ -14,27 +14,81 @@ _This package assumes that your code will run in an **ES2015+** environment. If
 
 ### Plugins API
 
-The plugins API contains the following methods:
+<!-- START TOKEN(Autogenerated API docs) -->
 
-#### `wp.plugins.registerPlugin( name: string, settings: Object )`
+#### getPlugin
 
-This method registers a new plugin.
+[src/index.js#L2-L2](src/index.js#L2-L2)
 
-This method takes two arguments:
+Returns a registered plugin settings.
 
-1. `name`: A string identifying the plugin. Must be unique across all registered plugins.
-2. `settings`: An object containing the following data:
-    - `icon: string | WPElement | Function` - An icon to be shown in the UI. It can be a slug
-      of the [Dashicon](https://developer.wordpress.org/resource/dashicons/#awards),
-      or an element (or function returning an element) if you choose to render your own SVG.
-    - `render`: A component containing the UI elements to be rendered.
+**Parameters**
 
-See [the edit-post module documentation](/packages/edit-post/README.md) for available components.
+-   **name** `string`: Plugin name.
+
+**Returns**
+
+`?Object`: Plugin setting.
+
+#### getPlugins
+
+[src/index.js#L2-L2](src/index.js#L2-L2)
+
+Returns all registered plugins.
+
+**Returns**
+
+`Array`: Plugin settings.
+
+#### PluginArea
+
+[src/index.js#L1-L1](src/index.js#L1-L1)
+
+A component that renders all plugin fills in a hidden div.
+
+**Usage**
+
+```js
+// Using ES5 syntax
+var el = wp.element.createElement;
+var PluginArea = wp.plugins.PluginArea;
+
+function Layout() {
+	return el(
+		'div',
+		{},
+		'Content of the page',
+		PluginArea
+	);
+}
+```
+
+```js
+// Using ESNext syntax
+const { PluginArea } = wp.plugins;
+
+const Layout = () => (
+	<div>
+		Content of the page
+		<PluginArea />
+	</div>
+);
+```
+
+**Returns**
+
+`WPElement`: Plugin area.
+
+#### registerPlugin
+
+[src/index.js#L2-L2](src/index.js#L2-L2)
+
+Registers a plugin to the editor.
+
+**Usage**
 
-_Example:_
-{% codetabs %}
-{% ES5 %}
 ```js
+// Using ES5 syntax
 var el = wp.element.createElement;
 var Fragment = wp.element.Fragment;
 var PluginSidebar = wp.editPost.PluginSidebar;
@@ -68,8 +122,8 @@ registerPlugin( 'plugin-name', {
 } );
 ```
 
-{% ESNext %}
-```jsx
+```js
+// Using ESNext syntax
 const { Fragment } = wp.element;
 const { PluginSidebar, PluginSidebarMoreMenuItem } = wp.editPost;
 const { registerPlugin } = wp.plugins;
@@ -95,72 +149,64 @@ registerPlugin( 'plugin-name', {
 	render: Component,
 } );
 ```
-{% end %}
 
-#### `wp.plugins.unregisterPlugin( name: string )`
+**Parameters**
+
+-   **name** `string`: A string identifying the plugin. Must be unique across all registered plugins.
+-   **settings** `Object`: The settings for this plugin.
+-   **settings.icon** `(string|WPElement|Function)`: An icon to be shown in the UI. It can be a slug of the Dashicon, or an element (or function returning an element) if you choose to render your own SVG.
+-   **settings.render** `Function`: A component containing the UI elements to be rendered.
 
-This method unregisters an existing plugin.
+**Returns**
 
-This method takes one argument:
+`Object`: The final plugin settings object.
 
-1. `name`: A string identifying the plugin.
+#### unregisterPlugin
 
-_Example:_
+[src/index.js#L2-L2](src/index.js#L2-L2)
 
-{% codetabs %}
+Unregisters a plugin by name.
+
+**Usage**
 
-{% ES5 %}
 ```js
+// Using ES5 syntax
 var unregisterPlugin = wp.plugins.unregisterPlugin;
 
 unregisterPlugin( 'plugin-name' );
 ```
 
-{% ESNext %}
-
 ```js
+// Using ESNext syntax
 const { unregisterPlugin } = wp.plugins;
 
 unregisterPlugin( 'plugin-name' );
 ```
-{% end %}
 
-### Components
+**Parameters**
 
-#### `PluginArea`
+-   **name** `string`: Plugin name.
 
-A component that renders all registered plugins in a hidden div.
+**Returns**
 
-_Example:_
-{% codetabs %}
+`?WPPlugin`: The previous plugin settings object, if it has been successfully unregistered; otherwise `undefined`.
 
-{% ES5 %}
-```js
-var el = wp.element.createElement;
-var PluginArea = wp.plugins.PluginArea;
+#### withPluginContext
 
-function Layout() {
-	return el(
-		'div',
-		{},
-		'Content of the page',
-		PluginArea
-	);
-}
-```
+[src/index.js#L1-L1](src/index.js#L1-L1)
 
-{% ESNext %}
+A Higher Order Component used to inject Plugin context to the
+wrapped component.
 
-```jsx
-const { PluginArea } = wp.plugins;
+**Parameters**
 
-const Layout = () => (
-	<div>
-		Content of the page
-		<PluginArea />
-	</div>
-);
-```
-{% end %}
+-   **mapContextToProps** `Function`: Function called on every context change, expected to return object of props to merge with the component's own props.
+
+**Returns**
+
+`Component`: Enhanced component with injected context as props.
+
+
+<!-- END TOKEN(Autogenerated API docs) -->
 
 <br/><br/><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>
diff --git a/packages/plugins/src/api/index.js b/packages/plugins/src/api/index.js
@@ -20,10 +20,76 @@ const plugins = {};
 /**
  * Registers a plugin to the editor.
  *
- * @param {string}                    name            The name of the plugin.
+ * @param {string}                    name            A string identifying the plugin. Must be unique across all registered plugins.
  * @param {Object}                    settings        The settings for this plugin.
- * @param {Function}                  settings.render The function that renders the plugin.
- * @param {string|WPElement|Function} settings.icon   An icon to be shown in the UI.
+ * @param {string|WPElement|Function} settings.icon   An icon to be shown in the UI. It can be a slug of the Dashicon,
+ * or an element (or function returning an element) if you choose to render your own SVG.
+ * @param {Function}                  settings.render A component containing the UI elements to be rendered.
+ *
+ * @example <caption>ES5</caption>
+ * ```js
+ * // Using ES5 syntax
+ * var el = wp.element.createElement;
+ * var Fragment = wp.element.Fragment;
+ * var PluginSidebar = wp.editPost.PluginSidebar;
+ * var PluginSidebarMoreMenuItem = wp.editPost.PluginSidebarMoreMenuItem;
+ * var registerPlugin = wp.plugins.registerPlugin;
+ *
+ * function Component() {
+ * 	return el(
+ * 		Fragment,
+ * 		{},
+ * 		el(
+ * 			PluginSidebarMoreMenuItem,
+ * 			{
+ * 				target: 'sidebar-name',
+ * 			},
+ * 			'My Sidebar'
+ * 		),
+ * 		el(
+ * 			PluginSidebar,
+ * 			{
+ * 				name: 'sidebar-name',
+ * 				title: 'My Sidebar',
+ * 			},
+ * 			'Content of the sidebar'
+ * 		)
+ * 	);
+ * }
+ * registerPlugin( 'plugin-name', {
+ * 	icon: 'smiley',
+ * 	render: Component,
+ * } );
+ * ```
+ *
+ * @example <caption>ESNext</caption>
+ * ```js
+ * // Using ESNext syntax
+ * const { Fragment } = wp.element;
+ * const { PluginSidebar, PluginSidebarMoreMenuItem } = wp.editPost;
+ * const { registerPlugin } = wp.plugins;
+ *
+ * const Component = () => (
+ * 	<Fragment>
+ * 		<PluginSidebarMoreMenuItem
+ * 			target="sidebar-name"
+ * 		>
+ * 			My Sidebar
+ * 		</PluginSidebarMoreMenuItem>
+ * 		<PluginSidebar
+ * 			name="sidebar-name"
+ * 			title="My Sidebar"
+ * 		>
+ * 			Content of the sidebar
+ * 		</PluginSidebar>
+ * 	</Fragment>
+ * );
+ *
+ * registerPlugin( 'plugin-name', {
+ * 	icon: 'smiley',
+ * 	render: Component,
+ * } );
+ * ```
  *
  * @return {Object} The final plugin settings object.
  */
@@ -77,6 +143,22 @@ export function registerPlugin( name, settings ) {
  *
  * @param {string} name Plugin name.
  *
+ * @example <caption>ES5</caption>
+ * ```js
+ * // Using ES5 syntax
+ * var unregisterPlugin = wp.plugins.unregisterPlugin;
+ *
+ * unregisterPlugin( 'plugin-name' );
+ * ```
+ *
+ * @example <caption>ESNext</caption>
+ * ```js
+ * // Using ESNext syntax
+ * const { unregisterPlugin } = wp.plugins;
+ *
+ * unregisterPlugin( 'plugin-name' );
+ * ```
+ *
  * @return {?WPPlugin} The previous plugin settings object, if it has been
  *                     successfully unregistered; otherwise `undefined`.
  */

diff --git a/packages/plugins/src/components/plugin-area/index.js b/packages/plugins/src/components/plugin-area/index.js
@@ -18,6 +18,35 @@ import { getPlugins } from '../../api';
 /**
  * A component that renders all plugin fills in a hidden div.
  *
+ * @example <caption>ES5</caption>
+ * ```js
+ * // Using ES5 syntax
+ * var el = wp.element.createElement;
+ * var PluginArea = wp.plugins.PluginArea;
+ *
+ * function Layout() {
+ * 	return el(
+ * 		'div',
+ * 		{},
+ * 		'Content of the page',
+ * 		PluginArea
+ * 	);
+ * }
+ * ```
+ *
+ * @example <caption>ESNext</caption>
+ * ```js
+ * // Using ESNext syntax
+ * const { PluginArea } = wp.plugins;
+ *
+ * const Layout = () => (
+ * 	<div>
+ * 		Content of the page
+ * 		<PluginArea />
+ * 	</div>
+ * );
+ * ```
+ *
  * @return {WPElement} Plugin area.
  */
 class PluginArea extends Component {