From 01d42938033eec24d8b9d17100e6685e7151acda Mon Sep 17 00:00:00 2001
From: Yury Semikhatsky <yurys@chromium.org>
Date: Wed, 10 Apr 2024 10:05:54 -0700
Subject: [PATCH] chore: class link generation in release notes (#30324)

---
 utils/doclint/linkUtils.js     | 33 ++++++++++++++++++++++++++-------
 utils/generate_types/index.js  |  2 +-
 utils/render_release_notes.mjs |  2 +-
 3 files changed, 28 insertions(+), 9 deletions(-)

diff --git a/utils/doclint/linkUtils.js b/utils/doclint/linkUtils.js
index 469c3764dd..89bdabc316 100644
--- a/utils/doclint/linkUtils.js
+++ b/utils/doclint/linkUtils.js
@@ -13,10 +13,14 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
+/** @typedef {'Types'|'ReleaseNotesMd'} OutputType */
+
 // @ts-check
 const toKebabCase = require('lodash/kebabCase.js')
+const Documentation = require('./documentation');
 
-const createMarkdownLink = (languagePath, member, text) => {
+function createMarkdownLink(languagePath, member, text) {
   const className = toKebabCase(member.clazz.name);
   const memberName = toKebabCase(member.name);
   let hash = null;
@@ -28,18 +32,33 @@ const createMarkdownLink = (languagePath, member, text) => {
 };
 
 /**
- * @param {string} language 
- * @returns {import('../doclint/documentation').Renderer}
+ * @param {string} languagePath
+ * @param {Documentation.Class} clazz
+ * @returns {string}
  */
-function docsLinkRendererForLanguage(language) {
+function createClassMarkdownLink(languagePath, clazz) {
+  return `[${clazz.name}](https://playwright.dev${languagePath}/docs/api/class-${clazz.name.toLowerCase()})`;
+};
+
+/**
+ * @param {string} language 
+ * @param {OutputType} outputType
+ * @returns {Documentation.Renderer}
+ */
+function docsLinkRendererForLanguage(language, outputType) {
   const languagePath = languageToRelativeDocsPath(language);
   return ({ clazz, member, param, option }) => {
     if (param)
       return `\`${param}\``;
     if (option)
       return `\`${option}\``;
-    if (clazz)
-      return `{@link ${clazz.name}}`;
+    if (clazz) {
+      if (outputType === 'Types')
+        return `{@link ${clazz.name}}`;
+      if (outputType === 'ReleaseNotesMd')
+        return createClassMarkdownLink(languagePath, clazz);
+      throw new Error(`Unexpected output type ${outputType}`);
+    }
     if (!member || !member.clazz)
       throw new Error('Internal error');
     const className = member.clazz.varName === 'playwrightAssertions' ? '' : member.clazz.varName + '.';
@@ -92,7 +111,7 @@ function assertionArgument(className) {
 }
 
 /**
- * @param {import('../doclint/documentation').Member[]} args
+ * @param {Documentation.Member[]} args
  */
 function renderJSSignature(args) {
   const tokens = [];
diff --git a/utils/generate_types/index.js b/utils/generate_types/index.js
index 34fa8fae56..24966b1704 100644
--- a/utils/generate_types/index.js
+++ b/utils/generate_types/index.js
@@ -81,7 +81,7 @@ class TypesGenerator {
    * @returns {Promise<string>}
    */
   async generateTypes(overridesFile) {
-    this.documentation.setLinkRenderer(docsLinkRendererForLanguage('js'));
+    this.documentation.setLinkRenderer(docsLinkRendererForLanguage('js', 'Types'));
     this.documentation.setCodeGroupsTransformer('js', tabs => tabs.filter(tab => tab.value === 'ts').map(tab => tab.spec));
     this.documentation.generateSourceCodeComments();
 
diff --git a/utils/render_release_notes.mjs b/utils/render_release_notes.mjs
index e9cdd45253..4d50acb7bc 100644
--- a/utils/render_release_notes.mjs
+++ b/utils/render_release_notes.mjs
@@ -40,7 +40,7 @@ if (language === 'js') {
       .mergeWith(parseApi(path.join(documentationRoot, 'test-reporter-api')));
 }
 
-documentation.setLinkRenderer(docsLinkRendererForLanguage(language));
+documentation.setLinkRenderer(docsLinkRendererForLanguage(language, 'ReleaseNotesMd'));
 const content = fs.readFileSync(path.join(documentationRoot, `release-notes-${language}.md`)).toString();
 let nodes = md.parse(content);
 documentation.renderLinksInNodes(nodes);