Set up docs

WordPress · Mar 6, 2019 · 3a411c8 · 3a411c8
1 parent d397c28
commit 3a411c8
Show file tree

Hide file tree

Showing 4 changed files with 27 additions and 24 deletions.
diff --git a/bin/update-readmes.js b/bin/update-readmes.js
@@ -4,7 +4,7 @@ const path = require( 'path' );
 const childProcess = require( 'child_process' );
 
 const packages = [
-	//'a11y',
+	'a11y',
 	//'autop',
 	//'blob',
 	//'block-editor',

diff --git a/packages/a11y/README.md b/packages/a11y/README.md
@@ -24,25 +24,14 @@ Create the live regions.
 
 ### speak
 
-[src/index.js#L40-L54](src/index.js#L40-L54)
+[src/index.js#L52-L66](src/index.js#L52-L66)
 
-Update the ARIA live notification area text node.
+Allows you to easily announce dynamic interface updates to screen readers using ARIA live regions.
+This module is inspired by the `speak` function in wp-a11y.js
 
-**Parameters**
-
--   **message** `string`: The message to be announced by Assistive Technologies.
--   **ariaLive** `string`: Optional. The politeness level for aria-live. Possible values: polite or assertive. Default polite.
-
-
-<!-- END TOKEN(Autogenerated API docs) -->
-
-## Usage
-
-Allows you to easily announce dynamic interface updates to screen readers using ARIA live regions. This module is inspired by the `speak` function in wp-a11y.js
+**Usage**
 
-To make the `wp.a11y.speak` functionality more universally available, we've decided to create a dedicated JS module for it, called `speak`. Usage is very simple:
-
-```JS
+```js
 import { speak } from '@wordpress/a11y';
 
 // For polite messages that shouldn't interrupt what screen readers are currently announcing.
@@ -52,6 +41,14 @@ speak( 'The message you want to send to the ARIA live region' );
 speak( 'The message you want to send to the ARIA live region', 'assertive' );
 ```
 
+**Parameters**
+
+-   **message** `string`: The message to be announced by Assistive Technologies.
+-   **ariaLive** `string`: Optional. The politeness level for aria-live. Possible values: polite or assertive. Default polite.
+
+
+<!-- END TOKEN(Autogenerated API docs) -->
+
 ### Background
 
 For context I'll quote [this article on WordPress.org](https://make.wordpress.org/accessibility/2015/04/15/let-wordpress-speak-new-in-wordpress-4-2/) by [@joedolson](https://github.com/joedolson):

diff --git a/packages/a11y/package.json b/packages/a11y/package.json
@@ -25,13 +25,7 @@
 		"@babel/runtime": "^7.3.1",
 		"@wordpress/dom-ready": "file:../dom-ready"
 	},
-	"devDependencies": {
-		"@wordpress/docgen": "file:../docgen"
-	},
 	"publishConfig": {
 		"access": "public"
-	},
-	"scripts": {
-		"docs:generate": "docgen ./src/index.js --output ./README.md --to-token"
 	}
 }
diff --git a/packages/a11y/src/index.js b/packages/a11y/src/index.js
@@ -31,11 +31,23 @@ export const setup = function() {
 domReady( setup );
 
 /**
- * Update the ARIA live notification area text node.
+ * Allows you to easily announce dynamic interface updates to screen readers using ARIA live regions.
+ * This module is inspired by the `speak` function in wp-a11y.js
  *
  * @param {string} message  The message to be announced by Assistive Technologies.
  * @param {string} ariaLive Optional. The politeness level for aria-live. Possible values:
  *                          polite or assertive. Default polite.
+ *
+ * @example
+ * ```js
+ * import { speak } from '@wordpress/a11y';
+ *
+ * // For polite messages that shouldn't interrupt what screen readers are currently announcing.
+ * speak( 'The message you want to send to the ARIA live region' );
+ *
+ * // For assertive messages that should interrupt what screen readers are currently announcing.
+ * speak( 'The message you want to send to the ARIA live region', 'assertive' );
+ * ```
  */
 export const speak = function( message, ariaLive ) {
 	// Clear previous messages to allow repeated strings being read out.