Fix new-lines being stripped for @see descriptions

WordPress · Feb 9, 2021 · 1bda459 · 1bda459
1 parent a17a974
commit 1bda459
Show file tree

Hide file tree

Showing 5 changed files with 22 additions and 9 deletions.
diff --git a/packages/block-editor/src/store/actions.js b/packages/block-editor/src/store/actions.js
@@ -546,7 +546,7 @@ export function insertBlock(
  * @param {?boolean}   updateSelection If true block selection will be updated.  If false, block selection will not change. Defaults to true.
  * @param {?Object}  meta             Optional Meta values to be passed to the action object.
  *
- *  @return {Object} Action object.
+ * @return {Object} Action object.
  */
 export function* insertBlocks(
 	blocks,

diff --git a/packages/docgen/src/get-jsdoc-from-token.js b/packages/docgen/src/get-jsdoc-from-token.js
@@ -27,7 +27,10 @@ module.exports = ( token ) => {
 			jsdoc.tags = jsdoc.tags.map( ( tag ) => {
 				return {
 					...tag,
-					description: tag.description.trim(),
+					description:
+						tag.description === '\n'
+							? tag.description.trim()
+							: tag.description,
 				};
 			} );
 		}

diff --git a/packages/docgen/src/markdown/formatter.js b/packages/docgen/src/markdown/formatter.js
@@ -108,9 +108,9 @@ module.exports = (
 				'Related',
 				getSymbolTagsByName( symbol, 'see', 'link' ),
 				( tag ) =>
-					`\n- ${ cleanSpaces(
-						`${ tag.name } ${ tag.description }`
-					) }`,
+					`\n- ${ tag.name.trim() }${
+						tag.description ? ' ' : ''
+					}${ tag.description.trim() }`,
 				docs
 			);
 			formatExamples( getSymbolTagsByName( symbol, 'example' ), docs );

diff --git a/packages/docgen/src/test/get-jsdoc-from-token.js b/packages/docgen/src/test/get-jsdoc-from-token.js
@@ -44,14 +44,14 @@ describe( 'JSDoc', () => {
 				},
 				{
 					tag: 'param',
-					description: 'The second param to add.',
+					description: 'The second param to add.\n',
 					type: 'number',
 					name: 'secondParam',
 				},
 				{
 					tag: 'example',
 					description:
-						'```js\nconst addResult = sum( 1, 3 );\nconsole.log( addResult ); // will yield 4\n```',
+						' \n\n```js\nconst addResult = sum( 1, 3 );\nconsole.log( addResult ); // will yield 4\n```\n',
 				},
 				{
 					tag: 'return',

diff --git a/packages/escape-html/README.md b/packages/escape-html/README.md
@@ -43,7 +43,16 @@ Returns an escaped attribute value.
 
 _Related_
 
--   <https://w3c.github.io/html/syntax.html#elements-attributes> "[...] the text cannot contain an ambiguous ampersand [...] must not contain any literal U+0022 QUOTATION MARK characters (")"  Note we also escape the greater than symbol, as this is used by wptexturize to split HTML strings. This is a WordPress specific fix  Note that if a resolution for Trac#45387 comes to fruition, it is no longer necessary for `__unstableEscapeGreaterThan` to be used.  See: <https://core.trac.wordpress.org/ticket/45387>
+-   <https://w3c.github.io/html/syntax.html#elements-attributes> "[...] the text cannot contain an ambiguous ampersand [...] must not contain
+    any literal U+0022 QUOTATION MARK characters (")"
+
+Note we also escape the greater than symbol, as this is used by wptexturize to
+split HTML strings. This is a WordPress specific fix
+
+Note that if a resolution for Trac#45387 comes to fruition, it is no longer
+necessary for `__unstableEscapeGreaterThan` to be used.
+
+See: <https://core.trac.wordpress.org/ticket/45387>
 
 _Parameters_
 
@@ -73,7 +82,8 @@ Returns an escaped HTML element value.
 
 _Related_
 
--   <https://w3c.github.io/html/syntax.html#writing-html-documents-elements> "the text must not contain the character U+003C LESS-THAN SIGN (\<) or an ambiguous ampersand."
+-   <https://w3c.github.io/html/syntax.html#writing-html-documents-elements> "the text must not contain the character U+003C LESS-THAN SIGN (\<) or an
+    ambiguous ampersand."
 
 _Parameters_