Docge: Add basic handling for the @SInCE tag (#43550)

WordPress · Aug 24, 2022 · d012e2a · d012e2a
1 parent a498e31
commit d012e2a
Show file tree

Hide file tree

Showing 7 changed files with 43 additions and 2 deletions.
diff --git a/packages/core-data/README.md b/packages/core-data/README.md
@@ -831,6 +831,10 @@ _Returns_
 
 -   `EntityRecordResolution< RecordType >`: Entity record data.
 
+_Changelog_
+
+`6.1.0` Introduced in WordPress core.
+
 ### useEntityRecords
 
 Resolves the specified entity records.
@@ -875,6 +879,10 @@ _Returns_
 
 -   `EntityRecordsResolution< RecordType >`: Entity records data.
 
+_Changelog_
+
+`6.1.0` Introduced in WordPress core.
+
 ### useResourcePermissions
 
 Resolves resource permissions.
@@ -941,6 +949,10 @@ _Returns_
 
 -   `ResourcePermissionsResolution< IdType >`: Entity records data.
 
+_Changelog_
+
+`6.1.0` Introduced in WordPress core.
+
 <!-- END TOKEN(Autogenerated hooks|src/hooks/index.ts) -->
 
 ## Contributing to this package

diff --git a/packages/core-data/src/hooks/use-entity-record.ts b/packages/core-data/src/hooks/use-entity-record.ts
@@ -56,6 +56,8 @@ export interface Options {
 /**
  * Resolves the specified entity record.
  *
+ * @since 6.1.0 Introduced in WordPress core.
+ *
  * @param  kind     Kind of the entity, e.g. `root` or a `postType`. See rootEntitiesConfig in ../entities.ts for a list of available kinds.
  * @param  name     Name of the entity, e.g. `plugin` or a `post`. See rootEntitiesConfig in ../entities.ts for a list of available names.
  * @param  recordId ID of the requested entity record.

diff --git a/packages/core-data/src/hooks/use-entity-records.ts b/packages/core-data/src/hooks/use-entity-records.ts
@@ -24,6 +24,8 @@ const EMPTY_ARRAY = [];
 /**
  * Resolves the specified entity records.
  *
+ * @since 6.1.0 Introduced in WordPress core.
+ *
  * @param  kind      Kind of the entity, e.g. `root` or a `postType`. See rootEntitiesConfig in ../entities.ts for a list of available kinds.
  * @param  name      Name of the entity, e.g. `plugin` or a `post`. See rootEntitiesConfig in ../entities.ts for a list of available names.
  * @param  queryArgs Optional HTTP query description for how to fetch the data, passed to the requested API endpoint.

diff --git a/packages/core-data/src/hooks/use-query-select.ts b/packages/core-data/src/hooks/use-query-select.ts
@@ -35,6 +35,9 @@ interface QuerySelectResponse< Data > {
  * Like useSelect, but the selectors return objects containing
  * both the original data AND the resolution info.
  *
+ * @since 6.1.0 Introduced in WordPress core.
+ * @private
+ *
  * @param {Function} mapQuerySelect see useSelect
  * @param {Array}    deps           see useSelect
  *
@@ -71,7 +74,7 @@ interface QuerySelectResponse< Data > {
  *
  * @return {QuerySelectResponse} Queried data.
  */
-export default function __experimentalUseQuerySelect( mapQuerySelect, deps ) {
+export default function useQuerySelect( mapQuerySelect, deps ) {
 	return useSelect( ( select, registry ) => {
 		const resolve = ( store ) => enrichSelectors( select( store ) );
 		return mapQuerySelect( resolve, registry );

diff --git a/packages/core-data/src/hooks/use-resource-permissions.ts b/packages/core-data/src/hooks/use-resource-permissions.ts
@@ -44,6 +44,8 @@ type ResourcePermissionsResolution< IdType > = [
 /**
  * Resolves resource permissions.
  *
+ * @since 6.1.0 Introduced in WordPress core.
+ *
  * @param  resource The resource in question, e.g. media.
  * @param  id       ID of a specific resource entry, if needed, e.g. 10.
  *

diff --git a/packages/docgen/lib/markdown/formatter.js b/packages/docgen/lib/markdown/formatter.js
@@ -35,6 +35,24 @@ const formatExamples = ( tags, docs ) => {
 	}
 };
 
+const formatSince = ( tags, docs ) => {
+	if ( tags && tags.length > 0 ) {
+		docs.push( '\n' );
+		docs.push( '\n' );
+		docs.push( '*Changelog*' );
+		docs.push( '\n' );
+		docs.push( '\n' );
+		docs.push(
+			...tags.map(
+				( tag ) =>
+					`\n${ cleanSpaces(
+						`\`${ tag.name }\` ${ tag.description }`
+					) }`
+			)
+		);
+	}
+};
+
 const formatDeprecated = ( tags, docs ) => {
 	if ( tags && tags.length > 0 ) {
 		docs.push( '\n' );
@@ -187,6 +205,7 @@ module.exports = (
 				},
 				docs
 			);
+			formatSince( getSymbolTagsByName( symbol, 'since' ), docs );
 			docs.push( '\n' );
 			docs.push( '\n' );
 		} );

diff --git a/packages/docgen/test/get-jsdoc-from-token.js b/packages/docgen/test/get-jsdoc-from-token.js
@@ -9,7 +9,7 @@ describe( 'JSDoc', () => {
 			getJSDocFromToken( {
 				leadingComments: [
 					{
-						value: '*\n * A function that adds two parameters.\n *\n * @deprecated Use native addition instead.\n * @since v2\n *\n * @see addition\n * @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Arithmetic_Operators\n *\n * @param {number} firstParam The first param to add.\n * @param {number} secondParam The second param to add.\n *\n *  @example\n *\n * ```js\n * const addResult = sum( 1, 3 );\n * console.log( addResult ); // will yield 4\n * ```\n *\n * @return {number} The result of adding the two params.\n ',
+						value: '*\n * A function that adds two parameters.\n *\n * @deprecated Use native addition instead.\n * @since v2 Introduced.\n *\n * @see addition\n * @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Arithmetic_Operators\n *\n * @param {number} firstParam The first param to add.\n * @param {number} secondParam The second param to add.\n *\n *  @example\n *\n * ```js\n * const addResult = sum( 1, 3 );\n * console.log( addResult ); // will yield 4\n * ```\n *\n * @return {number} The result of adding the two params.\n ',
 					},
 				],
 			} )
@@ -24,6 +24,7 @@ describe( 'JSDoc', () => {
 				{
 					tag: 'since',
 					name: 'v2',
+					description: 'Introduced.\n',
 				},
 				{
 					tag: 'see',