From c05645216d4a307bb22fc9ecc09f0207678c94a6 Mon Sep 17 00:00:00 2001
From: Andrea Fercia <a.fercia@gmail.com>
Date: Wed, 27 Mar 2019 19:10:22 +0100
Subject: [PATCH 1/3] Update the alt text description.

---
 packages/block-library/src/image/edit.js      | 10 +++++++++-
 packages/block-library/src/media-text/edit.js | 10 +++++++++-
 2 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/packages/block-library/src/image/edit.js b/packages/block-library/src/image/edit.js
index 51d2587591eda..8b96b43311450 100644
--- a/packages/block-library/src/image/edit.js
+++ b/packages/block-library/src/image/edit.js
@@ -28,6 +28,7 @@ import {
 	ToggleControl,
 	Toolbar,
 	withNotices,
+	ExternalLink,
 } from '@wordpress/components';
 import { compose } from '@wordpress/compose';
 import { withSelect } from '@wordpress/data';
@@ -456,7 +457,14 @@ class ImageEdit extends Component {
 						label={ __( 'Alt Text (Alternative Text)' ) }
 						value={ alt }
 						onChange={ this.updateAlt }
-						help={ __( 'Alternative text describes your image to people who can’t see it. Add a short description with its key details.' ) }
+						help={
+							<Fragment>
+								<ExternalLink href={ __( 'https://www.w3.org/WAI/tutorials/images/decision-tree' ) }>
+									{ __( 'Describe the purpose of the image' ) }
+								</ExternalLink>
+								{ __( 'Leave empty if the image is purely decorative.' ) }
+							</Fragment>
+						}
 					/>
 					{ ! isEmpty( imageSizeOptions ) && (
 						<SelectControl
diff --git a/packages/block-library/src/media-text/edit.js b/packages/block-library/src/media-text/edit.js
index 061d36ccf6c69..309909d4aacfc 100644
--- a/packages/block-library/src/media-text/edit.js
+++ b/packages/block-library/src/media-text/edit.js
@@ -21,6 +21,7 @@ import {
 	TextareaControl,
 	ToggleControl,
 	Toolbar,
+	ExternalLink,
 } from '@wordpress/components';
 /**
  * Internal dependencies
@@ -170,7 +171,14 @@ class MediaTextEdit extends Component {
 					label={ __( 'Alt Text (Alternative Text)' ) }
 					value={ mediaAlt }
 					onChange={ onMediaAltChange }
-					help={ __( 'Alternative text describes your image to people who can’t see it. Add a short description with its key details.' ) }
+					help={
+						<Fragment>
+							<ExternalLink href={ __( 'https://www.w3.org/WAI/tutorials/images/decision-tree' ) }>
+								{ __( 'Describe the purpose of the image' ) }
+							</ExternalLink>
+							{ __( 'Leave empty if the image is purely decorative.' ) }
+						</Fragment>
+					}
 				/> ) }
 			</PanelBody>
 		);

From 590a18279ceb88706fdba5e02e2cfee2c1325e8a Mon Sep 17 00:00:00 2001
From: Andrea Fercia <a.fercia@gmail.com>
Date: Thu, 28 Mar 2019 00:48:55 +0100
Subject: [PATCH 2/3] Make the links non-translatable.

---
 packages/block-library/src/image/edit.js      | 2 +-
 packages/block-library/src/media-text/edit.js | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/block-library/src/image/edit.js b/packages/block-library/src/image/edit.js
index 8b96b43311450..c6336b0350836 100644
--- a/packages/block-library/src/image/edit.js
+++ b/packages/block-library/src/image/edit.js
@@ -459,7 +459,7 @@ class ImageEdit extends Component {
 						onChange={ this.updateAlt }
 						help={
 							<Fragment>
-								<ExternalLink href={ __( 'https://www.w3.org/WAI/tutorials/images/decision-tree' ) }>
+								<ExternalLink href="https://www.w3.org/WAI/tutorials/images/decision-tree">
 									{ __( 'Describe the purpose of the image' ) }
 								</ExternalLink>
 								{ __( 'Leave empty if the image is purely decorative.' ) }
diff --git a/packages/block-library/src/media-text/edit.js b/packages/block-library/src/media-text/edit.js
index 309909d4aacfc..ccf77324a8ce8 100644
--- a/packages/block-library/src/media-text/edit.js
+++ b/packages/block-library/src/media-text/edit.js
@@ -173,7 +173,7 @@ class MediaTextEdit extends Component {
 					onChange={ onMediaAltChange }
 					help={
 						<Fragment>
-							<ExternalLink href={ __( 'https://www.w3.org/WAI/tutorials/images/decision-tree' ) }>
+							<ExternalLink href="https://www.w3.org/WAI/tutorials/images/decision-tree">
 								{ __( 'Describe the purpose of the image' ) }
 							</ExternalLink>
 							{ __( 'Leave empty if the image is purely decorative.' ) }

From 55fa4f6f38d55ac3ced647bdf000684e5079c49b Mon Sep 17 00:00:00 2001
From: Andrea Fercia <a.fercia@gmail.com>
Date: Thu, 28 Mar 2019 01:02:41 +0100
Subject: [PATCH 3/3] Update help prop documentation.

---
 packages/components/src/base-control/README.md     |  2 +-
 packages/components/src/checkbox-control/README.md |  6 +++---
 packages/components/src/radio-control/README.md    |  4 ++--
 packages/components/src/range-control/README.md    |  4 ++--
 packages/components/src/select-control/README.md   |  8 ++++----
 packages/components/src/text-control/README.md     |  4 ++--
 packages/components/src/textarea-control/README.md | 14 +++++++-------
 packages/components/src/toggle-control/README.md   |  7 +++----
 8 files changed, 24 insertions(+), 25 deletions(-)

diff --git a/packages/components/src/base-control/README.md b/packages/components/src/base-control/README.md
index b79ee413e2190..67e4896c8abab 100644
--- a/packages/components/src/base-control/README.md
+++ b/packages/components/src/base-control/README.md
@@ -45,7 +45,7 @@ If this property is added, a label will be generated using label property as the
 
 If this property is added, a help text will be generated using help property as the content.
 
-- Type: `String`
+- Type: `String|WPElement`
 - Required: No
 
 ### className
diff --git a/packages/components/src/checkbox-control/README.md b/packages/components/src/checkbox-control/README.md
index 91b50a09b2d97..c011fd2c56fe1 100644
--- a/packages/components/src/checkbox-control/README.md
+++ b/packages/components/src/checkbox-control/README.md
@@ -60,7 +60,7 @@ import { withState } from '@wordpress/compose';
 
 const MyCheckboxControl = withState( {
 	isChecked: true,
-} )( ( { isChecked, setState } ) => ( 
+} )( ( { isChecked, setState } ) => (
 	<CheckboxControl
 		heading="User"
 		label="Is author"
@@ -78,7 +78,7 @@ Props not included in this set will be applied to the input element.
 
 #### heading
 
-A heading for the input field, that appears above the checkbox. If the prop is not passed no heading will be rendered. 
+A heading for the input field, that appears above the checkbox. If the prop is not passed no heading will be rendered.
 
 - Type: `String`
 - Required: No
@@ -96,7 +96,7 @@ If no prop is passed an empty label is rendered.
 
 If this property is added, a help text will be generated using help property as the content.
 
-- Type: `String`
+- Type: `String|WPElement`
 - Required: No
 
 #### checked
diff --git a/packages/components/src/radio-control/README.md b/packages/components/src/radio-control/README.md
index 25ccbcafaa88e..2a55a81718fb1 100644
--- a/packages/components/src/radio-control/README.md
+++ b/packages/components/src/radio-control/README.md
@@ -62,7 +62,7 @@ import { withState } from '@wordpress/compose';
 
 const MyRadioControl = withState( {
 	option: 'a',
-} )( ( { option, setState } ) => ( 
+} )( ( { option, setState } ) => (
 	<RadioControl
 		label="User type"
 		help="The type of the current user"
@@ -91,7 +91,7 @@ If this property is added, a label will be generated using label property as the
 
 If this property is added, a help text will be generated using help property as the content.
 
-- Type: `String`
+- Type: `String|WPElement`
 - Required: No
 
 #### selected
diff --git a/packages/components/src/range-control/README.md b/packages/components/src/range-control/README.md
index 1f2024c8b6086..b0511fdaec2d7 100644
--- a/packages/components/src/range-control/README.md
+++ b/packages/components/src/range-control/README.md
@@ -96,7 +96,7 @@ import { withState } from '@wordpress/compose';
 
 const MyRangeControl = withState( {
         columns: 2,
-} )( ( { columns, setState } ) => ( 
+} )( ( { columns, setState } ) => (
     <RangeControl
         label="Columns"
         value={ columns }
@@ -123,7 +123,7 @@ If this property is added, a label will be generated using label property as the
 
 If this property is added, a help text will be generated using help property as the content.
 
-- Type: `String`
+- Type: `String|WPElement`
 - Required: No
 
 #### beforeIcon
diff --git a/packages/components/src/select-control/README.md b/packages/components/src/select-control/README.md
index 31c8dc5132a48..c7a1008be7c0c 100644
--- a/packages/components/src/select-control/README.md
+++ b/packages/components/src/select-control/README.md
@@ -16,7 +16,7 @@ SelectControl allow users to select from a single-option menu. It functions as a
 
 #### When to use a select control
 
-Use a select control when: 
+Use a select control when:
 
 - You want users to select a single option from a list.
 - There is a strong default option.
@@ -83,10 +83,10 @@ Render a user interface to select the size of an image.
 
     import { SelectControl } from '@wordpress/components';
     import { withState } from '@wordpress/compose';
-    
+
     const MySelectControl = withState( {
         size: '50%',
-    } )( ( { size, setState } ) => ( 
+    } )( ( { size, setState } ) => (
         <SelectControl
             label="Size"
             value={ size }
@@ -130,7 +130,7 @@ If this property is added, a label will be generated using label property as the
 #### help
 
 If this property is added, a help text will be generated using help property as the content.
-- Type: `String`
+- Type: `String|WPElement`
 - Required: No
 
 #### multiple
diff --git a/packages/components/src/text-control/README.md b/packages/components/src/text-control/README.md
index a66e6daadbd5b..6c1c214a27f02 100644
--- a/packages/components/src/text-control/README.md
+++ b/packages/components/src/text-control/README.md
@@ -13,7 +13,7 @@ import { withState } from '@wordpress/compose';
 
 const MyTextControl = withState( {
 	className: '',
-} )( ( { className, setState } ) => ( 
+} )( ( { className, setState } ) => (
 	<TextControl
 		label="Additional CSS Class"
 		value={ className }
@@ -38,7 +38,7 @@ If this property is added, a label will be generated using label property as the
 
 If this property is added, a help text will be generated using help property as the content.
 
-- Type: `String`
+- Type: `String|WPElement`
 - Required: No
 
 ### type
diff --git a/packages/components/src/textarea-control/README.md b/packages/components/src/textarea-control/README.md
index 672d13c5b6b1c..f5cd78d3ad508 100644
--- a/packages/components/src/textarea-control/README.md
+++ b/packages/components/src/textarea-control/README.md
@@ -33,7 +33,7 @@ Do not use TextareaControl if you need to let users enter shorter answers (no lo
 
 **Do**
 
-Use TextareaControl to let users to enter text longer than a single line. 
+Use TextareaControl to let users to enter text longer than a single line.
 
 ![](https://wordpress.org/gutenberg/files/2019/01/TextareaControl-Answers-Dont.png)
 
@@ -55,11 +55,11 @@ Containers improve the discoverability of text fields by creating contrast betwe
 ![](https://wordpress.org/gutenberg/files/2019/01/TextareaControl-Stroke-Do.png)
 
 **Do**
-Use a stroke around the container, which clearly indicates that users can input information. 
+Use a stroke around the container, which clearly indicates that users can input information.
 
 ![](https://wordpress.org/gutenberg/files/2019/01/TextareaControl-Stroke-Dont.png)
 
-**Don’t** 
+**Don’t**
 Use unclear visual markers to indicate a text field.
 
 ### Label text
@@ -78,10 +78,10 @@ When text input isn’t accepted, an error message can display instructions on h
 
     import { TextareaControl } from '@wordpress/components';
     import { withState } from '@wordpress/compose';
-    
+
     const MyTextareaControl = withState( {
         text: '',
-    } )( ( { text, setState } ) => ( 
+    } )( ( { text, setState } ) => (
         <TextareaControl
             label="Text"
             help="Enter some text"
@@ -93,7 +93,7 @@ When text input isn’t accepted, an error message can display instructions on h
 
 ### Props
 
-The set of props accepted by the component will be specified below. 
+The set of props accepted by the component will be specified below.
 
 Props not included in this set will be applied to the textarea element.
 
@@ -108,7 +108,7 @@ If this property is added, a label will be generated using label property as the
 
 If this property is added, a help text will be generated using help property as the content.
 
-- Type: `String`
+- Type: `String|WPElement`
 - Required: No
 
 #### rows
diff --git a/packages/components/src/toggle-control/README.md b/packages/components/src/toggle-control/README.md
index a55c0f30df8bb..fcc85df0af8b8 100644
--- a/packages/components/src/toggle-control/README.md
+++ b/packages/components/src/toggle-control/README.md
@@ -12,10 +12,10 @@ import { withState } from '@wordpress/compose';
 
 const MyToggleControl = withState( {
 	hasFixedBackground: false,
-} )( ( { hasFixedBackground, setState } ) => ( 
+} )( ( { hasFixedBackground, setState } ) => (
 	<ToggleControl
 		label="Fixed Background"
-		help={ hasFixedBackground ? 'Has fixed background.' : 'No fixed background.' } 
+		help={ hasFixedBackground ? 'Has fixed background.' : 'No fixed background.' }
 		checked={ hasFixedBackground }
 		onChange={ () => setState( ( state ) => ( { hasFixedBackground: ! state.hasFixedBackground } ) ) }
 	/>
@@ -37,7 +37,7 @@ If this property is added, a label will be generated using label property as the
 
 If this property is added, a help text will be generated using help property as the content.
 
-- Type: `String` | `Function`
+- Type: `String|WPElement`
 - Required: No
 
 ### checked
@@ -61,4 +61,3 @@ The class that will be added with `components-base-control` and `components-togg
 
 Type: String
 Required: No
-