Fix e2e-test-utils-playwright's jsdoc and types (#48266)

* Add @borrows to correctly copy the jsdoc

* Remove all jsdoc types in favor of typescript types

packages/e2e-test-utils-playwright/src/admin/get-page-error.ts

@@ -7,8 +7,6 @@ import type { Admin } from './';
  * Regular expression matching a displayed PHP error within a markup string.
  *
  * @see https://github.com/php/php-src/blob/598175e/main/main.c#L1257-L1297
- *
- * @type {RegExp}
  */
 const REGEXP_PHP_ERROR =
 	/(<b>)?(Fatal error|Recoverable fatal error|Warning|Parse error|Notice|Strict Standards|Deprecated|Unknown error)(<\/b>)?: (.*?) in (.*?) on line (<b>)?\d+(<\/b>)?/;
@@ -21,10 +19,8 @@ const REGEXP_PHP_ERROR =
  *
  * @see http://php.net/manual/en/function.error-reporting.php
  *
- * @param {Admin} this
- *
- * @return {Promise<?string>} Promise resolving to a string or null, depending
- *                            whether a page error is present.
+ * @param this
+ * @return Promise resolving to a string or null, depending whether a page error is present.
  */
 export async function getPageError( this: Admin ) {
 	const content = await this.page.content();

packages/e2e-test-utils-playwright/src/admin/index.ts

@@ -30,8 +30,12 @@ export class Admin {
 		this.pageUtils = pageUtils;
 	}
 
-	createNewPost = createNewPost.bind( this );
-	getPageError = getPageError.bind( this );
-	visitAdminPage = visitAdminPage.bind( this );
-	visitSiteEditor = visitSiteEditor.bind( this );
+	/** @borrows createNewPost as this.createNewPost */
+	createNewPost: typeof createNewPost = createNewPost.bind( this );
+	/** @borrows getPageError as this.getPageError */
+	getPageError: typeof getPageError = getPageError.bind( this );
+	/** @borrows visitAdminPage as this.visitAdminPage */
+	visitAdminPage: typeof visitAdminPage = visitAdminPage.bind( this );
+	/** @borrows visitSiteEditor as this.visitSiteEditor */
+	visitSiteEditor: typeof visitSiteEditor = visitSiteEditor.bind( this );
 }

packages/e2e-test-utils-playwright/src/admin/visit-admin-page.ts

@@ -11,9 +11,9 @@ import type { Admin } from './';
 /**
  * Visits admin page and handle errors.
  *
- * @param {Admin}  this
- * @param {string} adminPath String to be serialized as pathname.
- * @param {string} query     String to be serialized as query portion of URL.
+ * @param this
+ * @param adminPath String to be serialized as pathname.
+ * @param query     String to be serialized as query portion of URL.
  */
 export async function visitAdminPage(
 	this: Admin,

packages/e2e-test-utils-playwright/src/admin/visit-site-editor.ts

@@ -20,9 +20,9 @@ const CANVAS_SELECTOR = 'iframe[title="Editor canvas"i]';
  *
  * By default, it also skips the welcome guide. The option can be disabled if need be.
  *
- * @param {Admin}                 this
- * @param {SiteEditorQueryParams} query            Query params to be serialized as query portion of URL.
- * @param {boolean}               skipWelcomeGuide Whether to skip the welcome guide as part of the navigation.
+ * @param this
+ * @param query            Query params to be serialized as query portion of URL.
+ * @param skipWelcomeGuide Whether to skip the welcome guide as part of the navigation.
  */
 export async function visitSiteEditor(
 	this: Admin,

packages/e2e-test-utils-playwright/src/editor/click-block-options-menu-item.ts

@@ -6,8 +6,8 @@ import type { Editor } from './index';
 /**
  * Clicks a block toolbar button.
  *
- * @param {Editor} this
- * @param {string} label The text string of the button label.
+ * @param this
+ * @param label The text string of the button label.
  */
 export async function clickBlockOptionsMenuItem( this: Editor, label: string ) {
 	await this.clickBlockToolbarButton( 'Options' );

packages/e2e-test-utils-playwright/src/editor/click-block-toolbar-button.ts

@@ -6,8 +6,8 @@ import type { Editor } from './index';
 /**
  * Clicks a block toolbar button.
  *
- * @param {Editor} this
- * @param {string} label The text string of the button label.
+ * @param this
+ * @param label The text string of the button label.
  */
 export async function clickBlockToolbarButton( this: Editor, label: string ) {
 	await this.showBlockToolbar();

packages/e2e-test-utils-playwright/src/editor/get-edited-post-content.ts

@@ -6,9 +6,9 @@ import type { Editor } from './index';
 /**
  * Returns a promise which resolves with the edited post content (HTML string).
  *
- * @param {Editor} this
+ * @param this
  *
- * @return {Promise} Promise resolving with post content markup.
+ * @return Promise resolving with post content markup.
  */
 export async function getEditedPostContent( this: Editor ) {
 	return await this.page.evaluate( () =>

packages/e2e-test-utils-playwright/src/editor/index.ts

@@ -39,17 +39,35 @@ export class Editor {
 		return this.page.frame( 'editor-canvas' ) || this.page;
 	}
 
-	clickBlockOptionsMenuItem = clickBlockOptionsMenuItem.bind( this );
-	clickBlockToolbarButton = clickBlockToolbarButton.bind( this );
-	getBlocks = getBlocks.bind( this );
-	getEditedPostContent = getEditedPostContent.bind( this );
-	insertBlock = insertBlock.bind( this );
-	openDocumentSettingsSidebar = openDocumentSettingsSidebar.bind( this );
-	openPreviewPage = openPreviewPage.bind( this );
-	publishPost = publishPost.bind( this );
-	saveSiteEditorEntities = saveSiteEditorEntities.bind( this );
-	selectBlocks = selectBlocks.bind( this );
-	setContent = setContent.bind( this );
-	showBlockToolbar = showBlockToolbar.bind( this );
-	transformBlockTo = transformBlockTo.bind( this );
+	/** @borrows clickBlockOptionsMenuItem as this.clickBlockOptionsMenuItem */
+	clickBlockOptionsMenuItem: typeof clickBlockOptionsMenuItem =
+		clickBlockOptionsMenuItem.bind( this );
+	/** @borrows clickBlockToolbarButton as this.clickBlockToolbarButton */
+	clickBlockToolbarButton: typeof clickBlockToolbarButton =
+		clickBlockToolbarButton.bind( this );
+	/** @borrows getBlocks as this.getBlocks */
+	getBlocks: typeof getBlocks = getBlocks.bind( this );
+	/** @borrows getEditedPostContent as this.getEditedPostContent */
+	getEditedPostContent: typeof getEditedPostContent =
+		getEditedPostContent.bind( this );
+	/** @borrows insertBlock as this.insertBlock */
+	insertBlock: typeof insertBlock = insertBlock.bind( this );
+	/** @borrows openDocumentSettingsSidebar as this.openDocumentSettingsSidebar */
+	openDocumentSettingsSidebar: typeof openDocumentSettingsSidebar =
+		openDocumentSettingsSidebar.bind( this );
+	/** @borrows openPreviewPage as this.openPreviewPage */
+	openPreviewPage: typeof openPreviewPage = openPreviewPage.bind( this );
+	/** @borrows publishPost as this.publishPost */
+	publishPost: typeof publishPost = publishPost.bind( this );
+	/** @borrows saveSiteEditorEntities as this.saveSiteEditorEntities */
+	saveSiteEditorEntities: typeof saveSiteEditorEntities =
+		saveSiteEditorEntities.bind( this );
+	/** @borrows selectBlocks as this.selectBlocks */
+	selectBlocks: typeof selectBlocks = selectBlocks.bind( this );
+	/** @borrows setContent as this.setContent */
+	setContent: typeof setContent = setContent.bind( this );
+	/** @borrows showBlockToolbar as this.showBlockToolbar */
+	showBlockToolbar: typeof showBlockToolbar = showBlockToolbar.bind( this );
+	/** @borrows transformBlockTo as this.transformBlockTo */
+	transformBlockTo: typeof transformBlockTo = transformBlockTo.bind( this );
 }

packages/e2e-test-utils-playwright/src/editor/insert-block.ts

@@ -12,8 +12,8 @@ interface BlockRepresentation {
 /**
  * Insert a block.
  *
- * @param {Editor}              this
- * @param {BlockRepresentation} blockRepresentation Inserted block representation.
+ * @param this
+ * @param blockRepresentation Inserted block representation.
  */
 async function insertBlock(
 	this: Editor,

packages/e2e-test-utils-playwright/src/editor/open-document-settings-sidebar.ts

@@ -7,7 +7,7 @@ import type { Editor } from './index';
  * Clicks on the button in the header which opens Document Settings sidebar when
  * it is closed.
  *
- * @param {Editor} this
+ * @param this
  */
 export async function openDocumentSettingsSidebar( this: Editor ) {
 	const toggleButton = this.page

packages/e2e-test-utils-playwright/src/editor/preview.ts

@@ -11,9 +11,9 @@ import type { Editor } from './index';
 /**
  * Opens the preview page of an edited post.
  *
- * @param {Editor} this
+ * @param this
  *
- * @return {Promise<Page>} preview page.
+ * @return preview page.
  */
 export async function openPreviewPage( this: Editor ): Promise< Page > {
 	const editorTopBar = this.page.locator(

packages/e2e-test-utils-playwright/src/editor/publish-post.ts

@@ -7,7 +7,7 @@ import type { Editor } from './index';
  * Publishes the post, resolving once the request is complete (once a notice
  * is displayed).
  *
- * @param {Editor} this
+ * @param this
  */
 export async function publishPost( this: Editor ) {
 	await this.page.click( 'role=button[name="Publish"i]' );

packages/e2e-test-utils-playwright/src/editor/show-block-toolbar.ts

@@ -7,7 +7,7 @@ import type { Editor } from './index';
  * The block toolbar is not always visible while typing.
  * Call this function to reveal it.
  *
- * @param {Editor} this
+ * @param this
  */
 export async function showBlockToolbar( this: Editor ) {
 	// Move the mouse to disable the isTyping mode. We need at least three

packages/e2e-test-utils-playwright/src/editor/site-editor.ts

@@ -6,7 +6,7 @@ import type { Editor } from './index';
 /**
  * Save entities in the site editor. Assumes the editor is in a dirty state.
  *
- * @param {Editor} this
+ * @param this
  */
 export async function saveSiteEditorEntities( this: Editor ) {
 	await this.page.click(

packages/e2e-test-utils-playwright/src/editor/transform-block-to.ts

@@ -6,8 +6,8 @@ import type { Editor } from './index';
 /**
  * Clicks the default block appender.
  *
- * @param {Editor} this
- * @param {string} name Block name.
+ * @param this
+ * @param name Block name.
  */
 export async function transformBlockTo( this: Editor, name: string ) {
 	await this.page.evaluate(

packages/e2e-test-utils-playwright/src/page-utils/index.ts

@@ -30,12 +30,20 @@ class PageUtils {
 		this.browser = this.context.browser()!;
 	}
 
-	dragFiles = dragFiles.bind( this );
-	isCurrentURL = isCurrentURL.bind( this );
-	pressKeyTimes = pressKeyTimes.bind( this );
-	pressKeyWithModifier = pressKeyWithModifier.bind( this );
-	setBrowserViewport = setBrowserViewport.bind( this );
-	setClipboardData = setClipboardData.bind( this );
+	/** @borrows dragFiles as this.dragFiles */
+	dragFiles: typeof dragFiles = dragFiles.bind( this );
+	/** @borrows isCurrentURL as this.isCurrentURL */
+	isCurrentURL: typeof isCurrentURL = isCurrentURL.bind( this );
+	/** @borrows pressKeyTimes as this.pressKeyTimes */
+	pressKeyTimes: typeof pressKeyTimes = pressKeyTimes.bind( this );
+	/** @borrows pressKeyWithModifier as this.pressKeyWithModifier */
+	pressKeyWithModifier: typeof pressKeyWithModifier =
+		pressKeyWithModifier.bind( this );
+	/** @borrows setBrowserViewport as this.setBrowserViewport */
+	setBrowserViewport: typeof setBrowserViewport =
+		setBrowserViewport.bind( this );
+	/** @borrows setClipboardData as this.setClipboardData */
+	setClipboardData: typeof setClipboardData = setClipboardData.bind( this );
 }
 
 export { PageUtils };

packages/e2e-test-utils-playwright/src/page-utils/is-current-url.ts

@@ -7,10 +7,10 @@ import type { PageUtils } from './';
 /**
  * Checks if current path of the URL matches the provided path.
  *
- * @param {PageUtils} this
- * @param {string}    path String to be serialized as pathname.
+ * @param this
+ * @param path String to be serialized as pathname.
  *
- * @return {boolean} Boolean represents whether current URL is or not a WordPress path.
+ * @return Boolean represents whether current URL is or not a WordPress path.
  */
 export function isCurrentURL( this: PageUtils, path: string ) {
 	const currentURL = new URL( this.page.url() );

packages/e2e-test-utils-playwright/src/request-utils/comments.ts

@@ -22,8 +22,8 @@ export interface User {
 /**
  * Create new comment using the REST API.
  *
- * @param {RequestUtils}         this
- * @param {CreateCommentPayload} payload
+ * @param this
+ * @param payload
  */
 export async function createComment(
 	this: RequestUtils,
@@ -48,7 +48,7 @@ export async function createComment(
 /**
  * Delete all comments using the REST API.
  *
- * @param {RequestUtils} this
+ * @param this
  */
 export async function deleteAllComments( this: RequestUtils ) {
 	// List all comments.

packages/e2e-test-utils-playwright/src/request-utils/index.ts

@@ -118,40 +118,76 @@ class RequestUtils {
 		this.baseURL = baseURL;
 	}
 
-	login = login.bind( this );
-	setupRest = setupRest.bind( this );
+	/** @borrows login as this.login */
+	login: typeof login = login.bind( this );
+	/** @borrows setupRest as this.setupRest */
+	setupRest: typeof setupRest = setupRest.bind( this );
 	// .bind() drops the generic types. Re-casting it to keep the type signature.
-	rest = rest.bind( this ) as typeof rest;
-	getMaxBatchSize = getMaxBatchSize.bind( this );
+	rest: typeof rest = rest.bind( this ) as typeof rest;
+	/** @borrows getMaxBatchSize as this.getMaxBatchSize */
+	getMaxBatchSize: typeof getMaxBatchSize = getMaxBatchSize.bind( this );
 	// .bind() drops the generic types. Re-casting it to keep the type signature.
-	batchRest = batchRest.bind( this ) as typeof batchRest;
-	getPluginsMap = getPluginsMap.bind( this );
-	activatePlugin = activatePlugin.bind( this );
-	deactivatePlugin = deactivatePlugin.bind( this );
-	activateTheme = activateTheme.bind( this );
-	deleteAllBlocks = deleteAllBlocks;
-	createPost = createPost.bind( this );
-	deleteAllPosts = deleteAllPosts.bind( this );
-	createClassicMenu = createClassicMenu.bind( this );
-	createNavigationMenu = createNavigationMenu.bind( this );
-	deleteAllMenus = deleteAllMenus.bind( this );
-	getNavigationMenus = getNavigationMenus.bind( this );
-	createComment = createComment.bind( this );
-	deleteAllComments = deleteAllComments.bind( this );
-	deleteAllWidgets = deleteAllWidgets.bind( this );
-	addWidgetBlock = addWidgetBlock.bind( this );
-	deleteAllTemplates = deleteAllTemplates.bind( this );
-	resetPreferences = resetPreferences.bind( this );
-	listMedia = listMedia.bind( this );
-	uploadMedia = uploadMedia.bind( this );
-	deleteMedia = deleteMedia.bind( this );
-	deleteAllMedia = deleteAllMedia.bind( this );
-	createUser = createUser.bind( this );
-	deleteAllUsers = deleteAllUsers.bind( this );
-	getSiteSettings = getSiteSettings.bind( this );
-	updateSiteSettings = updateSiteSettings.bind( this );
-	deleteAllPages = deleteAllPages.bind( this );
-	createPage = createPage.bind( this );
+	batchRest: typeof batchRest = batchRest.bind( this ) as typeof batchRest;
+	/** @borrows getPluginsMap as this.getPluginsMap */
+	getPluginsMap: typeof getPluginsMap = getPluginsMap.bind( this );
+	/** @borrows activatePlugin as this.activatePlugin */
+	activatePlugin: typeof activatePlugin = activatePlugin.bind( this );
+	/** @borrows deactivatePlugin as this.deactivatePlugin */
+	deactivatePlugin: typeof deactivatePlugin = deactivatePlugin.bind( this );
+	/** @borrows activateTheme as this.activateTheme */
+	activateTheme: typeof activateTheme = activateTheme.bind( this );
+	/** @borrows deleteAllBlocks as this.deleteAllBlocks */
+	deleteAllBlocks = deleteAllBlocks.bind( this );
+	/** @borrows createPost as this.createPost */
+	createPost: typeof createPost = createPost.bind( this );
+	/** @borrows deleteAllPosts as this.deleteAllPosts */
+	deleteAllPosts: typeof deleteAllPosts = deleteAllPosts.bind( this );
+	/** @borrows createClassicMenu as this.createClassicMenu */
+	createClassicMenu: typeof createClassicMenu =
+		createClassicMenu.bind( this );
+	/** @borrows createNavigationMenu as this.createNavigationMenu */
+	createNavigationMenu: typeof createNavigationMenu =
+		createNavigationMenu.bind( this );
+	/** @borrows deleteAllMenus as this.deleteAllMenus */
+	deleteAllMenus: typeof deleteAllMenus = deleteAllMenus.bind( this );
+	/** @borrows getNavigationMenus as this.getNavigationMenus */
+	getNavigationMenus: typeof getNavigationMenus =
+		getNavigationMenus.bind( this );
+	/** @borrows createComment as this.createComment */
+	createComment: typeof createComment = createComment.bind( this );
+	/** @borrows deleteAllComments as this.deleteAllComments */
+	deleteAllComments: typeof deleteAllComments =
+		deleteAllComments.bind( this );
+	/** @borrows deleteAllWidgets as this.deleteAllWidgets */
+	deleteAllWidgets: typeof deleteAllWidgets = deleteAllWidgets.bind( this );
+	/** @borrows addWidgetBlock as this.addWidgetBlock */
+	addWidgetBlock: typeof addWidgetBlock = addWidgetBlock.bind( this );
+	/** @borrows deleteAllTemplates as this.deleteAllTemplates */
+	deleteAllTemplates: typeof deleteAllTemplates =
+		deleteAllTemplates.bind( this );
+	/** @borrows resetPreferences as this.resetPreferences */
+	resetPreferences: typeof resetPreferences = resetPreferences.bind( this );
+	/** @borrows listMedia as this.listMedia */
+	listMedia: typeof listMedia = listMedia.bind( this );
+	/** @borrows uploadMedia as this.uploadMedia */
+	uploadMedia: typeof uploadMedia = uploadMedia.bind( this );
+	/** @borrows deleteMedia as this.deleteMedia */
+	deleteMedia: typeof deleteMedia = deleteMedia.bind( this );
+	/** @borrows deleteAllMedia as this.deleteAllMedia */
+	deleteAllMedia: typeof deleteAllMedia = deleteAllMedia.bind( this );
+	/** @borrows createUser as this.createUser */
+	createUser: typeof createUser = createUser.bind( this );
+	/** @borrows deleteAllUsers as this.deleteAllUsers */
+	deleteAllUsers: typeof deleteAllUsers = deleteAllUsers.bind( this );
+	/** @borrows getSiteSettings as this.getSiteSettings */
+	getSiteSettings: typeof getSiteSettings = getSiteSettings.bind( this );
+	/** @borrows updateSiteSettings as this.updateSiteSettings */
+	updateSiteSettings: typeof updateSiteSettings =
+		updateSiteSettings.bind( this );
+	/** @borrows deleteAllPages as this.deleteAllPages */
+	deleteAllPages: typeof deleteAllPages = deleteAllPages.bind( this );
+	/** @borrows createPage as this.createPage */
+	createPage: typeof createPage = createPage.bind( this );
 }
 
 export type { StorageState };

packages/e2e-test-utils-playwright/src/request-utils/menus.ts

@@ -56,8 +56,8 @@ export async function createClassicMenu( this: RequestUtils, name: string ) {
 /**
  * Create a navigation menu
  *
- * @param  menuData navigation menu post data.
- * @return {string} Menu content.
+ * @param menuData navigation menu post data.
+ * @return Menu content.
  */
 export async function createNavigationMenu(
 	this: RequestUtils,