From d07f6cfc5c9fdfee7fe07e8586bcd8cd4fd5ca42 Mon Sep 17 00:00:00 2001
From: Dmitry Gozman <dgozman@gmail.com>
Date: Thu, 26 Sep 2024 06:31:42 -0700
Subject: [PATCH] docs: check that description has an empty line before it
 (#32830)

---
 docs/src/api/class-androiddevice.md       | 4 +++-
 docs/src/api/class-page.md                | 8 ++++++--
 docs/src/api/params.md                    | 2 --
 docs/src/test-api/class-test.md           | 3 ++-
 packages/playwright-core/types/types.d.ts | 2 +-
 utils/doclint/api_parser.js               | 9 ++++++---
 6 files changed, 18 insertions(+), 10 deletions(-)

diff --git a/docs/src/api/class-androiddevice.md b/docs/src/api/class-androiddevice.md
index 4c2a9d97bd..729b36f922 100644
--- a/docs/src/api/class-androiddevice.md
+++ b/docs/src/api/class-androiddevice.md
@@ -177,7 +177,9 @@ Launches a process in the shell on the device and returns a socket to communicat
 
 ### param: AndroidDevice.open.command
 * since: v1.9
-- `command` <[string]> Shell command to execute.
+- `command` <[string]>
+
+Shell command to execute.
 
 ## async method: AndroidDevice.pinchClose
 * since: v1.9
diff --git a/docs/src/api/class-page.md b/docs/src/api/class-page.md
index 3461ac9928..b376edfb1d 100644
--- a/docs/src/api/class-page.md
+++ b/docs/src/api/class-page.md
@@ -4093,12 +4093,16 @@ await page.GotoAsync("https://www.microsoft.com");
 ### param: Page.setViewportSize.width
 * since: v1.10
 * langs: csharp, java
-- `width` <[int]> page width in pixels.
+- `width` <[int]>
+
+Page width in pixels.
 
 ### param: Page.setViewportSize.height
 * since: v1.10
 * langs: csharp, java
-- `height` <[int]> page height in pixels.
+- `height` <[int]>
+
+Page height in pixels.
 
 ## async method: Page.tap
 * since: v1.8
diff --git a/docs/src/api/params.md b/docs/src/api/params.md
index f4545b0268..1f9c03d77a 100644
--- a/docs/src/api/params.md
+++ b/docs/src/api/params.md
@@ -765,8 +765,6 @@ not recorded. Make sure to call [`method: BrowserContext.close`] for videos to b
 * langs: csharp, java, python
   - alias-python: record_video_size
 - `recordVideoSize` <[Object]>
-  If `viewport` is not configured explicitly the video size defaults to 800x450. Actual picture of each page will be
-  scaled down if necessary to fit the specified size.
   - `width` <[int]> Video frame width.
   - `height` <[int]> Video frame height.
 
diff --git a/docs/src/test-api/class-test.md b/docs/src/test-api/class-test.md
index b6ae7d1522..4706d462f0 100644
--- a/docs/src/test-api/class-test.md
+++ b/docs/src/test-api/class-test.md
@@ -1713,7 +1713,8 @@ Whether to box the step in the report. Defaults to `false`. When the step is box
 ### option: Test.step.location
 * since: v1.48
 - `location` <[Location]>
-Specifies a custom location for the step to be shown in test reports. By default, location of the [`method: Test.step`] call is shown.
+
+Specifies a custom location for the step to be shown in test reports and trace viewer. By default, location of the [`method: Test.step`] call is shown.
 
 ## method: Test.use
 * since: v1.10
diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts
index 6fc76d0dbd..4e4b632462 100644
--- a/packages/playwright-core/types/types.d.ts
+++ b/packages/playwright-core/types/types.d.ts
@@ -16825,7 +16825,7 @@ export interface AndroidDevice {
 
   /**
    * Launches a process in the shell on the device and returns a socket to communicate with the launched process.
-   * @param command
+   * @param command Shell command to execute.
    */
   open(command: string): Promise<AndroidSocket>;
 
diff --git a/utils/doclint/api_parser.js b/utils/doclint/api_parser.js
index f2f53cbd1f..a4d504ea48 100644
--- a/utils/doclint/api_parser.js
+++ b/utils/doclint/api_parser.js
@@ -165,7 +165,7 @@ class ApiParser {
     if (!name)
       throw new Error('Invalid member name ' + spec.text);
     if (match[1] === 'param') {
-      const arg = this.parseProperty(spec);
+      const arg = this.parseProperty(spec, match[2]);
       if (!arg)
         return;
       arg.name = name;
@@ -182,7 +182,7 @@ class ApiParser {
       }
     } else {
       // match[1] === 'option'
-      const p = this.parseProperty(spec);
+      const p = this.parseProperty(spec, match[2]);
       if (!p)
         return;
       let options = method.argsArray.find(o => o.name === 'options');
@@ -198,11 +198,14 @@ class ApiParser {
 
   /**
    * @param {MarkdownHeaderNode} spec
+   * @param {string} memberName
    * @returns {docs.Member | null}
    */
-  parseProperty(spec) {
+  parseProperty(spec, memberName) {
     const param = childrenWithoutProperties(spec)[0];
     const text = /** @type {string}*/(param.text);
+    if (text.substring(text.lastIndexOf('>') + 1).trim())
+      throw new Error(`Extra information after type while processing "${memberName}".\nYou probably need an extra empty line before the description.\n================\n${text}`);
     let typeStart = text.indexOf('<');
     while ('?e'.includes(text[typeStart - 1]))
       typeStart--;