From 89894e15d299608be5ac62ddb56f54e4c1342f7e Mon Sep 17 00:00:00 2001
From: Yury Semikhatsky <yurys@chromium.org>
Date: Thu, 19 Aug 2021 14:52:35 -0700
Subject: [PATCH] docs: fix @link reference for method with alias (#577)

---
 .../com/microsoft/playwright/Browser.java     | 18 +++++++++-------
 .../microsoft/playwright/BrowserContext.java  |  2 +-
 .../com/microsoft/playwright/BrowserType.java |  9 ++++----
 .../microsoft/playwright/ConsoleMessage.java  |  4 ++--
 .../java/com/microsoft/playwright/Page.java   | 10 ++++-----
 .../playwright/tools/ApiGenerator.java        | 21 +++++++++++++++----
 6 files changed, 40 insertions(+), 24 deletions(-)

diff --git a/playwright/src/main/java/com/microsoft/playwright/Browser.java b/playwright/src/main/java/com/microsoft/playwright/Browser.java
index 61283af9..cf7b6d33 100644
--- a/playwright/src/main/java/com/microsoft/playwright/Browser.java
+++ b/playwright/src/main/java/com/microsoft/playwright/Browser.java
@@ -61,10 +61,11 @@ public interface Browser extends AutoCloseable {
      */
     public Boolean acceptDownloads;
     /**
-     * When using {@link Page#goto Page.goto()}, {@link Page#route Page.route()}, {@link Page#waitForURL Page.waitForURL()},
-     * {@link Page#waitForRequest Page.waitForRequest()}, or {@link Page#waitForResponse Page.waitForResponse()} it takes the
-     * base URL in consideration by using the <a href="https://developer.mozilla.org/en-US/docs/Web/API/URL/URL">{@code URL()}</a>
-     * constructor for building the corresponding URL. Examples:
+     * When using {@link Page#navigate Page.navigate()}, {@link Page#route Page.route()}, {@link Page#waitForURL
+     * Page.waitForURL()}, {@link Page#waitForRequest Page.waitForRequest()}, or {@link Page#waitForResponse
+     * Page.waitForResponse()} it takes the base URL in consideration by using the <a
+     * href="https://developer.mozilla.org/en-US/docs/Web/API/URL/URL">{@code URL()}</a> constructor for building the corresponding
+     * URL. Examples:
      * <ul>
      * <li> baseURL: {@code http://localhost:3000} and navigating to {@code /bar.html} results in {@code http://localhost:3000/bar.html}</li>
      * <li> baseURL: {@code http://localhost:3000/foo/} and navigating to {@code ./bar.html} results in {@code http://localhost:3000/foo/bar.html}</li>
@@ -332,10 +333,11 @@ public interface Browser extends AutoCloseable {
      */
     public Boolean acceptDownloads;
     /**
-     * When using {@link Page#goto Page.goto()}, {@link Page#route Page.route()}, {@link Page#waitForURL Page.waitForURL()},
-     * {@link Page#waitForRequest Page.waitForRequest()}, or {@link Page#waitForResponse Page.waitForResponse()} it takes the
-     * base URL in consideration by using the <a href="https://developer.mozilla.org/en-US/docs/Web/API/URL/URL">{@code URL()}</a>
-     * constructor for building the corresponding URL. Examples:
+     * When using {@link Page#navigate Page.navigate()}, {@link Page#route Page.route()}, {@link Page#waitForURL
+     * Page.waitForURL()}, {@link Page#waitForRequest Page.waitForRequest()}, or {@link Page#waitForResponse
+     * Page.waitForResponse()} it takes the base URL in consideration by using the <a
+     * href="https://developer.mozilla.org/en-US/docs/Web/API/URL/URL">{@code URL()}</a> constructor for building the corresponding
+     * URL. Examples:
      * <ul>
      * <li> baseURL: {@code http://localhost:3000} and navigating to {@code /bar.html} results in {@code http://localhost:3000/bar.html}</li>
      * <li> baseURL: {@code http://localhost:3000/foo/} and navigating to {@code ./bar.html} results in {@code http://localhost:3000/foo/bar.html}</li>
diff --git a/playwright/src/main/java/com/microsoft/playwright/BrowserContext.java b/playwright/src/main/java/com/microsoft/playwright/BrowserContext.java
index 65f9e77f..ec7fbde6 100644
--- a/playwright/src/main/java/com/microsoft/playwright/BrowserContext.java
+++ b/playwright/src/main/java/com/microsoft/playwright/BrowserContext.java
@@ -658,7 +658,7 @@ public interface BrowserContext extends AutoCloseable {
    * <ul>
    * <li> {@link Page#goBack Page.goBack()}</li>
    * <li> {@link Page#goForward Page.goForward()}</li>
-   * <li> {@link Page#goto Page.goto()}</li>
+   * <li> {@link Page#navigate Page.navigate()}</li>
    * <li> {@link Page#reload Page.reload()}</li>
    * <li> {@link Page#setContent Page.setContent()}</li>
    * <li> {@link Page#waitForNavigation Page.waitForNavigation()}</li>
diff --git a/playwright/src/main/java/com/microsoft/playwright/BrowserType.java b/playwright/src/main/java/com/microsoft/playwright/BrowserType.java
index 2df847aa..8722ad32 100644
--- a/playwright/src/main/java/com/microsoft/playwright/BrowserType.java
+++ b/playwright/src/main/java/com/microsoft/playwright/BrowserType.java
@@ -279,10 +279,11 @@ public interface BrowserType {
      */
     public List<String> args;
     /**
-     * When using {@link Page#goto Page.goto()}, {@link Page#route Page.route()}, {@link Page#waitForURL Page.waitForURL()},
-     * {@link Page#waitForRequest Page.waitForRequest()}, or {@link Page#waitForResponse Page.waitForResponse()} it takes the
-     * base URL in consideration by using the <a href="https://developer.mozilla.org/en-US/docs/Web/API/URL/URL">{@code URL()}</a>
-     * constructor for building the corresponding URL. Examples:
+     * When using {@link Page#navigate Page.navigate()}, {@link Page#route Page.route()}, {@link Page#waitForURL
+     * Page.waitForURL()}, {@link Page#waitForRequest Page.waitForRequest()}, or {@link Page#waitForResponse
+     * Page.waitForResponse()} it takes the base URL in consideration by using the <a
+     * href="https://developer.mozilla.org/en-US/docs/Web/API/URL/URL">{@code URL()}</a> constructor for building the corresponding
+     * URL. Examples:
      * <ul>
      * <li> baseURL: {@code http://localhost:3000} and navigating to {@code /bar.html} results in {@code http://localhost:3000/bar.html}</li>
      * <li> baseURL: {@code http://localhost:3000/foo/} and navigating to {@code ./bar.html} results in {@code http://localhost:3000/foo/bar.html}</li>
diff --git a/playwright/src/main/java/com/microsoft/playwright/ConsoleMessage.java b/playwright/src/main/java/com/microsoft/playwright/ConsoleMessage.java
index 39d13631..c5e63ad5 100644
--- a/playwright/src/main/java/com/microsoft/playwright/ConsoleMessage.java
+++ b/playwright/src/main/java/com/microsoft/playwright/ConsoleMessage.java
@@ -19,11 +19,11 @@ package com.microsoft.playwright;
 import java.util.*;
 
 /**
- * {@code ConsoleMessage} objects are dispatched by page via the {@link Page#onConsole Page.onConsole()} event.
+ * {@code ConsoleMessage} objects are dispatched by page via the {@link Page#onConsoleMessage Page.onConsoleMessage()} event.
  */
 public interface ConsoleMessage {
   /**
-   * List of arguments passed to a {@code console} function call. See also {@link Page#onConsole Page.onConsole()}.
+   * List of arguments passed to a {@code console} function call. See also {@link Page#onConsoleMessage Page.onConsoleMessage()}.
    */
   List<JSHandle> args();
   /**
diff --git a/playwright/src/main/java/com/microsoft/playwright/Page.java b/playwright/src/main/java/com/microsoft/playwright/Page.java
index aabb7265..950e02ea 100644
--- a/playwright/src/main/java/com/microsoft/playwright/Page.java
+++ b/playwright/src/main/java/com/microsoft/playwright/Page.java
@@ -3135,7 +3135,7 @@ public interface Page extends AutoCloseable {
    * <p> <strong>NOTE:</strong> Headless mode doesn't support navigation to a PDF document. See the <a
    * href="https://bugs.chromium.org/p/chromium/issues/detail?id=761295">upstream issue</a>.
    *
-   * <p> Shortcut for main frame's {@link Frame#goto Frame.goto()}
+   * <p> Shortcut for main frame's {@link Frame#navigate Frame.navigate()}
    *
    * @param url URL to navigate page to. The url should include scheme, e.g. {@code https://}. When a {@code baseURL} via the context options was
    * provided and the passed URL is a path, it gets merged via the <a
@@ -3167,7 +3167,7 @@ public interface Page extends AutoCloseable {
    * <p> <strong>NOTE:</strong> Headless mode doesn't support navigation to a PDF document. See the <a
    * href="https://bugs.chromium.org/p/chromium/issues/detail?id=761295">upstream issue</a>.
    *
-   * <p> Shortcut for main frame's {@link Frame#goto Frame.goto()}
+   * <p> Shortcut for main frame's {@link Frame#navigate Frame.navigate()}
    *
    * @param url URL to navigate page to. The url should include scheme, e.g. {@code https://}. When a {@code baseURL} via the context options was
    * provided and the passed URL is a path, it gets merged via the <a
@@ -4186,7 +4186,7 @@ public interface Page extends AutoCloseable {
    * <ul>
    * <li> {@link Page#goBack Page.goBack()}</li>
    * <li> {@link Page#goForward Page.goForward()}</li>
-   * <li> {@link Page#goto Page.goto()}</li>
+   * <li> {@link Page#navigate Page.navigate()}</li>
    * <li> {@link Page#reload Page.reload()}</li>
    * <li> {@link Page#setContent Page.setContent()}</li>
    * <li> {@link Page#waitForNavigation Page.waitForNavigation()}</li>
@@ -4560,7 +4560,7 @@ public interface Page extends AutoCloseable {
   /**
    * Performs action and waits for a {@code ConsoleMessage} to be logged by in the page. If predicate is provided, it passes
    * {@code ConsoleMessage} value into the {@code predicate} function and waits for {@code predicate(message)} to return a truthy value. Will
-   * throw an error if the page is closed before the {@link Page#onConsole Page.onConsole()} event is fired.
+   * throw an error if the page is closed before the {@link Page#onConsoleMessage Page.onConsoleMessage()} event is fired.
    *
    * @param callback Callback that performs the action triggering the event.
    */
@@ -4570,7 +4570,7 @@ public interface Page extends AutoCloseable {
   /**
    * Performs action and waits for a {@code ConsoleMessage} to be logged by in the page. If predicate is provided, it passes
    * {@code ConsoleMessage} value into the {@code predicate} function and waits for {@code predicate(message)} to return a truthy value. Will
-   * throw an error if the page is closed before the {@link Page#onConsole Page.onConsole()} event is fired.
+   * throw an error if the page is closed before the {@link Page#onConsoleMessage Page.onConsoleMessage()} event is fired.
    *
    * @param callback Callback that performs the action triggering the event.
    */
diff --git a/tools/api-generator/src/main/java/com/microsoft/playwright/tools/ApiGenerator.java b/tools/api-generator/src/main/java/com/microsoft/playwright/tools/ApiGenerator.java
index c4b34441..d4a12235 100644
--- a/tools/api-generator/src/main/java/com/microsoft/playwright/tools/ApiGenerator.java
+++ b/tools/api-generator/src/main/java/com/microsoft/playwright/tools/ApiGenerator.java
@@ -160,6 +160,9 @@ abstract class Element {
     while (matcher.find()) {
       linkified += paragraph.substring(start, matcher.start());
       String name = matcher.group(2);
+      if (ApiGenerator.aliases.containsKey(name)) {
+        name = ApiGenerator.aliases.get(name);
+      }
       if ("event".equals(matcher.group(1))) {
         String[] parts = name.split("\\.");
         name = parts[0] + ".on" + toTitle(parts[1]);
@@ -1048,12 +1051,16 @@ class Enum extends TypeDefinition {
 }
 
 public class ApiGenerator {
+  // TODO: make it an instance field.
+  static final Map<String, String> aliases = new HashMap<>();
+
   ApiGenerator(Reader reader) throws IOException {
     JsonArray api = new Gson().fromJson(reader, JsonArray.class);
     File cwd = FileSystems.getDefault().getPath(".").toFile();
     File dir = new File(cwd, "playwright/src/main/java/com/microsoft/playwright");
     System.out.println("Writing files to: " + dir.getCanonicalPath());
-    filterOtherLangs(api);
+    Stack<String> path = new Stack<>();
+    filterOtherLangs(api, path);
     Map<String, TypeDefinition> topLevelTypes = new HashMap<>();
     for (JsonElement entry: api) {
       String name = entry.getAsJsonObject().get("name").getAsString();
@@ -1080,14 +1087,14 @@ public class ApiGenerator {
     }
   }
 
-  private static void filterOtherLangs(JsonElement json) {
+  private static void filterOtherLangs(JsonElement json, Stack<String> path) {
     if (json.isJsonArray()) {
       List<Integer> toRemove = new ArrayList<>();
       JsonArray array = json.getAsJsonArray();
       for (int i = 0; i < array.size(); i++) {
         JsonElement item = array.get(i);
         if (isSupported(item)) {
-          filterOtherLangs(item);
+          filterOtherLangs(item, path);
         } else {
           toRemove.add(i);
         }
@@ -1099,19 +1106,25 @@ public class ApiGenerator {
     } else if (json.isJsonObject()) {
       List<String> toRemove = new ArrayList<>();
       JsonObject object = json.getAsJsonObject();
+      path.push(object.has("name") ? object.get("name").getAsString() : "<none>");
       String alias = alias(object);
       if (alias != null) {
+        List<String> aliasPath = new ArrayList<>(path);
+        aliasPath.set(aliasPath.size() - 1, alias);
+        aliases.put(String.join(".", path), String.join(".", aliasPath));
         // Rename in place.
         object.addProperty("name", alias);
       }
       overrideType(object);
+
       for (Map.Entry<String, JsonElement> entry : object.entrySet()) {
         if (isSupported(entry.getValue())) {
-          filterOtherLangs(entry.getValue());
+          filterOtherLangs(entry.getValue(), path);
         } else {
           toRemove.add(entry.getKey());
         }
       }
+      path.pop();
       for (String key : toRemove) {
         object.remove(key);
       }