From 119e6167e25b2f8a2a473b497be65877112e944f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Rondley=20Greg=C3=B3rio?=
 <80141884+Rondleysg@users.noreply.github.com>
Date: Tue, 8 Apr 2025 19:46:18 -0300
Subject: [PATCH] docs: fixing deprecated tag display and returns (#14387)

* docs: fixing display when return has no description

* docs: fixing deprecated tag display to display description

* docs: fixing return typing

* docs: removing console.log

* docs: fixing HTMLElement return for WebdriverIO.Element
---
 packages/webdriverio/src/commands/browser/$$.ts              | 2 +-
 packages/webdriverio/src/commands/browser/$.ts               | 2 +-
 packages/webdriverio/src/commands/browser/custom$.ts         | 2 +-
 packages/webdriverio/src/commands/browser/react$$.ts         | 2 +-
 packages/webdriverio/src/commands/browser/react$.ts          | 2 +-
 packages/webdriverio/src/commands/browser/scroll.ts          | 4 ++--
 packages/webdriverio/src/commands/element/$$.ts              | 2 +-
 packages/webdriverio/src/commands/element/$.ts               | 2 +-
 packages/webdriverio/src/commands/element/custom$$.ts        | 2 +-
 packages/webdriverio/src/commands/element/custom$.ts         | 2 +-
 packages/webdriverio/src/commands/element/getElement.ts      | 2 +-
 packages/webdriverio/src/commands/element/getElements.ts     | 2 +-
 packages/webdriverio/src/commands/element/nextElement.ts     | 2 +-
 packages/webdriverio/src/commands/element/parentElement.ts   | 2 +-
 packages/webdriverio/src/commands/element/previousElement.ts | 2 +-
 packages/webdriverio/src/commands/element/react$$.ts         | 2 +-
 packages/webdriverio/src/commands/element/react$.ts          | 2 +-
 packages/webdriverio/src/commands/element/shadow$$.ts        | 2 +-
 packages/webdriverio/src/commands/element/shadow$.ts         | 2 +-
 scripts/templates/template.eta                               | 5 ++++-
 scripts/utils/formatter.ts                                   | 4 ++--
 21 files changed, 26 insertions(+), 23 deletions(-)

diff --git a/packages/webdriverio/src/commands/browser/$$.ts b/packages/webdriverio/src/commands/browser/$$.ts
index b43a7dc7f..66dfa9e4c 100644
--- a/packages/webdriverio/src/commands/browser/$$.ts
+++ b/packages/webdriverio/src/commands/browser/$$.ts
@@ -38,7 +38,7 @@ import type { Selector } from '../../types.js'
  *
  * @alias $$
  * @param {String|Function} selector  selector or JS Function to fetch multiple elements
- * @return {ElementArray}
+ * @return {WebdriverIO.ElementArray}
  * @example https://github.com/webdriverio/example-recipes/blob/59c122c809d44d343c231bde2af7e8456c8f086c/queryElements/example.html
  * @example https://github.com/webdriverio/example-recipes/blob/59c122c809d44d343c231bde2af7e8456c8f086c/queryElements/multipleElements.js#L6-L7
  * @example https://github.com/webdriverio/example-recipes/blob/59c122c809d44d343c231bde2af7e8456c8f086c/queryElements/multipleElements.js#L15-L24
diff --git a/packages/webdriverio/src/commands/browser/$.ts b/packages/webdriverio/src/commands/browser/$.ts
index 89a9cba11..61f24edee 100644
--- a/packages/webdriverio/src/commands/browser/$.ts
+++ b/packages/webdriverio/src/commands/browser/$.ts
@@ -57,7 +57,7 @@ import type { Selector } from '../../types.js'
  *
  * @alias $
  * @param {String|Function|Matcher} selector  selector, JS Function, or Matcher object to fetch a certain element
- * @return {Element}
+ * @return {WebdriverIO.Element}
  * @example https://github.com/webdriverio/example-recipes/blob/59c122c809d44d343c231bde2af7e8456c8f086c/queryElements/example.html
  * @example https://github.com/webdriverio/example-recipes/blob/59c122c809d44d343c231bde2af7e8456c8f086c/queryElements/singleElements.js#L9-L10
  * @example https://github.com/webdriverio/example-recipes/blob/59c122c809d44d343c231bde2af7e8456c8f086c/queryElements/singleElements.js#L16-L25
diff --git a/packages/webdriverio/src/commands/browser/custom$.ts b/packages/webdriverio/src/commands/browser/custom$.ts
index ad5c929f4..74a911972 100644
--- a/packages/webdriverio/src/commands/browser/custom$.ts
+++ b/packages/webdriverio/src/commands/browser/custom$.ts
@@ -28,7 +28,7 @@ import type { CustomStrategyFunction } from '../../types.js'
  * @example https://github.com/webdriverio/example-recipes/blob/f5730428ec3605e856e90bf58be17c9c9da891de/queryElements/customStrategy.js#L2-L11
  * @example https://github.com/webdriverio/example-recipes/blob/f5730428ec3605e856e90bf58be17c9c9da891de/queryElements/example.html#L8-L12
  * @example https://github.com/webdriverio/example-recipes/blob/f5730428ec3605e856e90bf58be17c9c9da891de/queryElements/customStrategy.js#L16-L19
- * @return {Element}
+ * @return {WebdriverIO.Element}
  */
 export async function custom$ (
     this: WebdriverIO.Browser,
diff --git a/packages/webdriverio/src/commands/browser/react$$.ts b/packages/webdriverio/src/commands/browser/react$$.ts
index 290872188..f8b2be729 100644
--- a/packages/webdriverio/src/commands/browser/react$$.ts
+++ b/packages/webdriverio/src/commands/browser/react$$.ts
@@ -36,7 +36,7 @@ import type { ReactSelectorOptions } from '../../types.js'
  * @param {ReactSelectorOptions=}                    options         React selector options
  * @param {Object=}                                  options.props   React props the element should contain
  * @param {`Array<any>|number|string|object|boolean`=} options.state  React state the element should be in
- * @return {ElementArray}
+ * @return {WebdriverIO.ElementArray}
  *
  */
 export async function react$$ (
diff --git a/packages/webdriverio/src/commands/browser/react$.ts b/packages/webdriverio/src/commands/browser/react$.ts
index 8725618cf..3a437772c 100644
--- a/packages/webdriverio/src/commands/browser/react$.ts
+++ b/packages/webdriverio/src/commands/browser/react$.ts
@@ -45,7 +45,7 @@ import type { ReactSelectorOptions } from '../../types.js'
  * @param {ReactSelectorOptions=}                    options         React selector options
  * @param {Object=}                                  options.props   React props the element should contain
  * @param {`Array<any>|number|string|object|boolean`=} options.state  React state the element should be in
- * @return {Element}
+ * @return {WebdriverIO.Element}
  *
  */
 export async function react$ (
diff --git a/packages/webdriverio/src/commands/browser/scroll.ts b/packages/webdriverio/src/commands/browser/scroll.ts
index 9e4313f42..8f0a5a81a 100644
--- a/packages/webdriverio/src/commands/browser/scroll.ts
+++ b/packages/webdriverio/src/commands/browser/scroll.ts
@@ -19,8 +19,8 @@ const log = logger('webdriverio')
  * </example>
  *
  * @alias element.scroll
- * @param {number=} x  horizontal scroll position (default: `0`)
- * @param {number=} y  vertical scroll position (default: `0`)
+ * @param {number} [x=0]  horizontal scroll position (default: `0`)
+ * @param {number} [y=0]  vertical scroll position (default: `0`)
  * @uses protocol/execute
  * @type utility
  *
diff --git a/packages/webdriverio/src/commands/element/$$.ts b/packages/webdriverio/src/commands/element/$$.ts
index 28c4d7f3d..5d0b39883 100644
--- a/packages/webdriverio/src/commands/element/$$.ts
+++ b/packages/webdriverio/src/commands/element/$$.ts
@@ -42,7 +42,7 @@
  *
  * @alias $$
  * @param {String|Function|Matcher} selector  selector, JS Function, or Matcher object to fetch multiple elements
- * @return {ElementArray}
+ * @return {WebdriverIO.ElementArray}
  * @example https://github.com/webdriverio/example-recipes/blob/59c122c809d44d343c231bde2af7e8456c8f086c/queryElements/example.html
  * @example https://github.com/webdriverio/example-recipes/blob/59c122c809d44d343c231bde2af7e8456c8f086c/queryElements/multipleElements.js#L6-L7
  * @example https://github.com/webdriverio/example-recipes/blob/59c122c809d44d343c231bde2af7e8456c8f086c/queryElements/multipleElements.js#L15-L24
diff --git a/packages/webdriverio/src/commands/element/$.ts b/packages/webdriverio/src/commands/element/$.ts
index de067f4e8..6e4312f14 100644
--- a/packages/webdriverio/src/commands/element/$.ts
+++ b/packages/webdriverio/src/commands/element/$.ts
@@ -57,7 +57,7 @@
  *
  * @alias $
  * @param {String|Function|Matcher} selector  selector, JS Function, or Matcher object to fetch a certain element
- * @return {Element}
+ * @return {WebdriverIO.Element}
  * @example https://github.com/webdriverio/example-recipes/blob/59c122c809d44d343c231bde2af7e8456c8f086c/queryElements/example.html
  * @example https://github.com/webdriverio/example-recipes/blob/59c122c809d44d343c231bde2af7e8456c8f086c/queryElements/singleElements.js#L9-L10
  * @example https://github.com/webdriverio/example-recipes/blob/59c122c809d44d343c231bde2af7e8456c8f086c/queryElements/singleElements.js#L16-L25
diff --git a/packages/webdriverio/src/commands/element/custom$$.ts b/packages/webdriverio/src/commands/element/custom$$.ts
index b25f27992..7f295540f 100644
--- a/packages/webdriverio/src/commands/element/custom$$.ts
+++ b/packages/webdriverio/src/commands/element/custom$$.ts
@@ -28,7 +28,7 @@ import type { CustomStrategyFunction } from '../../types.js'
  * @alias custom$$
  * @param {string} strategyName
  * @param {*} strategyArguments
- * @return {ElementArray}
+ * @return {WebdriverIO.ElementArray}
  */
 export async function custom$$ (
     this: WebdriverIO.Element,
diff --git a/packages/webdriverio/src/commands/element/custom$.ts b/packages/webdriverio/src/commands/element/custom$.ts
index b16681a67..86cea8743 100644
--- a/packages/webdriverio/src/commands/element/custom$.ts
+++ b/packages/webdriverio/src/commands/element/custom$.ts
@@ -30,7 +30,7 @@ import type { CustomStrategyFunction } from '../../types.js'
  * @example https://github.com/webdriverio/example-recipes/blob/f5730428ec3605e856e90bf58be17c9c9da891de/queryElements/customStrategy.js#L2-L11
  * @example https://github.com/webdriverio/example-recipes/blob/f5730428ec3605e856e90bf58be17c9c9da891de/queryElements/example.html#L8-L12
  * @example https://github.com/webdriverio/example-recipes/blob/f5730428ec3605e856e90bf58be17c9c9da891de/queryElements/customStrategy.js#L16-L19
- * @return {Element}
+ * @return {WebdriverIO.Element}
  */
 export async function custom$ (
     this: WebdriverIO.Element,
diff --git a/packages/webdriverio/src/commands/element/getElement.ts b/packages/webdriverio/src/commands/element/getElement.ts
index 8726ddddc..a26c3ad4b 100644
--- a/packages/webdriverio/src/commands/element/getElement.ts
+++ b/packages/webdriverio/src/commands/element/getElement.ts
@@ -13,7 +13,7 @@ import type { ChainablePromiseElement } from '../../types.js'
  * </example>
  *
  * @alias element.getElement
- * @return {Element}
+ * @return {WebdriverIO.Element}
  * @type utility
  *
  */
diff --git a/packages/webdriverio/src/commands/element/getElements.ts b/packages/webdriverio/src/commands/element/getElements.ts
index 3d75069a4..eb9ed7453 100644
--- a/packages/webdriverio/src/commands/element/getElements.ts
+++ b/packages/webdriverio/src/commands/element/getElements.ts
@@ -13,7 +13,7 @@ import type { ChainablePromiseArray } from '../../types.js'
  * </example>
  *
  * @alias element.getElements
- * @return {Element}
+ * @return {WebdriverIO.ElementArray}
  * @type utility
  *
  */
diff --git a/packages/webdriverio/src/commands/element/nextElement.ts b/packages/webdriverio/src/commands/element/nextElement.ts
index c51ae4456..2aae044e9 100644
--- a/packages/webdriverio/src/commands/element/nextElement.ts
+++ b/packages/webdriverio/src/commands/element/nextElement.ts
@@ -18,7 +18,7 @@
  * </example>
  *
  * @alias element.nextElement
- * @return {Element}
+ * @return {WebdriverIO.Element}
  * @type utility
  */
 
diff --git a/packages/webdriverio/src/commands/element/parentElement.ts b/packages/webdriverio/src/commands/element/parentElement.ts
index 75455d60c..0a1c22c18 100644
--- a/packages/webdriverio/src/commands/element/parentElement.ts
+++ b/packages/webdriverio/src/commands/element/parentElement.ts
@@ -18,7 +18,7 @@
  * </example>
  *
  * @alias element.parentElement
- * @return {Element}
+ * @return {WebdriverIO.Element}
  * @type utility
  */
 export function parentElement (this: WebdriverIO.Element) {
diff --git a/packages/webdriverio/src/commands/element/previousElement.ts b/packages/webdriverio/src/commands/element/previousElement.ts
index 003e1e70e..a1fcc6b98 100644
--- a/packages/webdriverio/src/commands/element/previousElement.ts
+++ b/packages/webdriverio/src/commands/element/previousElement.ts
@@ -18,7 +18,7 @@
  * </example>
  *
  * @alias element.previousElement
- * @return {Element}
+ * @return {WebdriverIO.Element}
  * @type utility
  */
 export function previousElement (this: WebdriverIO.Element) {
diff --git a/packages/webdriverio/src/commands/element/react$$.ts b/packages/webdriverio/src/commands/element/react$$.ts
index 1e642e6ce..75a70e14f 100644
--- a/packages/webdriverio/src/commands/element/react$$.ts
+++ b/packages/webdriverio/src/commands/element/react$$.ts
@@ -37,7 +37,7 @@ import type { ReactSelectorOptions } from '../../types.js'
  * @param {ReactSelectorOptions=}                    options         React selector options
  * @param {Object=}                                  options.props   React props the element should contain
  * @param {`Array<any>|number|string|object|boolean`=} options.state  React state the element should be in
- * @return {ElementArray}
+ * @return {WebdriverIO.ElementArray}
  *
  */
 export async function react$$(
diff --git a/packages/webdriverio/src/commands/element/react$.ts b/packages/webdriverio/src/commands/element/react$.ts
index 770011c9c..518fe761f 100644
--- a/packages/webdriverio/src/commands/element/react$.ts
+++ b/packages/webdriverio/src/commands/element/react$.ts
@@ -46,7 +46,7 @@ import type { ReactSelectorOptions } from '../../types.js'
  * @param {ReactSelectorOptions=}                    options         React selector options
  * @param {Object=}                                  options.props   React props the element should contain
  * @param {`Array<any>|number|string|object|boolean`=} options.state  React state the element should be in
- * @return {Element}
+ * @return {WebdriverIO.Element}
  *
  */
 export async function react$(
diff --git a/packages/webdriverio/src/commands/element/shadow$$.ts b/packages/webdriverio/src/commands/element/shadow$$.ts
index a5461a0c7..b9c8c2f7d 100644
--- a/packages/webdriverio/src/commands/element/shadow$$.ts
+++ b/packages/webdriverio/src/commands/element/shadow$$.ts
@@ -34,7 +34,7 @@ const log = logger('webdriverio')
  *
  * @alias element.shadow$$
  * @param {String|Function} selector  selector or JS Function to fetch a certain element
- * @return {ElementArray}
+ * @return {WebdriverIO.ElementArray}
  * @type utility
  *
  */
diff --git a/packages/webdriverio/src/commands/element/shadow$.ts b/packages/webdriverio/src/commands/element/shadow$.ts
index cc7beea84..34a3c8b29 100644
--- a/packages/webdriverio/src/commands/element/shadow$.ts
+++ b/packages/webdriverio/src/commands/element/shadow$.ts
@@ -32,7 +32,7 @@ const log = logger('webdriverio')
  *
  * @alias element.shadow$
  * @param {String|Function} selector  selector or JS Function to fetch a certain element
- * @return {Element}
+ * @return {WebdriverIO.Element}
  * @type utility
  *
  */
diff --git a/scripts/templates/template.eta b/scripts/templates/template.eta
index f633ca64f..b7c0127b3 100644
--- a/scripts/templates/template.eta
+++ b/scripts/templates/template.eta
@@ -114,7 +114,10 @@ const ext = it.path.extname(filename).slice(1);
 <% if (it.returns) { %>
 ##### Returns
 
-- **&lt;<%= it.returns.type %>&gt; <code><var><%= it.returns.name %></var></code>:** <%= it.returns.description %>
+- **&lt;<%= it.returns.type %>&gt;**
+    <% if (it.returns.description) { %>
+        **<code><var><%= it.returns.name %></var></code>:** <%= it.returns.description %>
+    <% } %>
 <% } %>
 
 <% if (it.throwsTags.length) { %>
diff --git a/scripts/utils/formatter.ts b/scripts/utils/formatter.ts
index decb30e7b..6c9ee7155 100644
--- a/scripts/utils/formatter.ts
+++ b/scripts/utils/formatter.ts
@@ -51,7 +51,7 @@ export default function (docfile: {
     const fires: string[] = []
     const listens: string[] = []
     const exampleReferences: string[] = []
-    let tagDeprecated = false
+    let tagDeprecated = ''
     let tagSee = ''
     let tagVersion = ''
     let tagAuthor = ''
@@ -141,7 +141,7 @@ export default function (docfile: {
             break
         }
         case 'deprecated': {
-            tagDeprecated = true
+            tagDeprecated = source[0].source.split('@deprecated')[1].trim()
             break
         }
         case 'mobileElement': {