chore: add comments to generated interfaces (#75)

Author: mxschmitt

generated_interfaces.go

@@ -437,7 +437,7 @@ func (p *pageImpl) Hover(selector string, options ...PageHoverOptions) error {
 	return p.mainFrame.Hover(selector, options...)
 }
 
-func (p *pageImpl) Isclosed() bool {
+func (p *pageImpl) IsClosed() bool {
 	return p.isClosed
 }
 

page.go

@@ -737,7 +737,7 @@
 			"selector string, options ...PageInnerTextOptions",
 			"(string, error)"
 		],
-		"Isclosed": [
+		"IsClosed": [
 			null,
 			"bool"
 		],

scripts/data/interfaces.json

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
+const { transformMethodNamesToGo, getAPIDocs } = require("./helpers")
 
 const interfaceData = require("./data/interfaces.json")
+const api = getAPIDocs()
 
 const transformInputParameters = (input) => {
   if (!input) return ""
@@ -14,14 +16,45 @@ const transformReturnParameters = (input) => {
   return `(${input})`
 }
 
+const writeComment = (comment) => {
+  const lines = comment.split("\n")
+  let inExample = false
+  let lastWasBlank = true
+  const out = []
+  for (const line of lines) {
+    if (!line.trim()) {
+      lastWasBlank = true
+      continue
+    }
+    if (line.trim() === "```js")
+      inExample = true
+    if (!inExample) {
+      if (lastWasBlank)
+        lastWasBlank = false
+      out.push(line.trim())
+    }
+    if (line.trim() === "```")
+      inExample = false
+  }
+
+  for (const line of out)
+    console.log(`// ${line}`)
+}
+
 console.log("package playwright")
 
 for (const [className, methods] of Object.entries(interfaceData)) {
+  if (api[className])
+    writeComment(api[className].comment)
   console.log(`type ${className} interface {`)
   for (const [funcName, funcData] of Object.entries(methods)) {
     if (funcData.length === 0) {
       console.log(funcName)
     } else {
+      const apiFunc = api[className] && Object.entries(api[className].methods).find(([item]) => transformMethodNamesToGo(item) === funcName)
+      if (apiFunc && apiFunc[1].comment)
+        writeComment(apiFunc[1].comment)
+
       const [inputTypes, returnTypes] = funcData
       console.log(`${funcName}(${transformInputParameters(inputTypes)}) ${transformReturnParameters(returnTypes)}`)
     }

scripts/generate-interfaces.js

@@ -32,16 +32,20 @@ const getAPIDocs = () => {
   }).toString())
 }
 
-const transformMethodNamesToGo = (funcName) => funcName
-  .replace("$$eval", "evalOnSelectorAll")
-  .replace("$eval", "evalOnSelector")
-  .replace("$$", "querySelectorAll")
-  .replace("$", "querySelector")
-  .replace("pdf", "PDF")
-  .replace("url", "URL")
-  .replace("json", "JSON")
+const transformMethodNamesToGo = (funcName) => {
+  const standardised = funcName
+    .replace("$$eval", "evalOnSelectorAll")
+    .replace("$eval", "evalOnSelector")
+    .replace("$$", "querySelectorAll")
+    .replace("$", "querySelector")
+    .replace("pdf", "PDF")
+    .replace("url", "URL")
+    .replace("json", "JSON")
+
+  return standardised[0].toUpperCase() + standardised.slice(1)
+}
 
 module.exports = {
   getAPIDocs,
-  transformMethodNamesToGo
+  transformMethodNamesToGo,
 }

scripts/helpers.js

@@ -17,11 +17,6 @@ const shouldIgnoreClass = ([k]) =>
   !k.startsWith("Firefox") &&
   !k.startsWith("WebKit")
 
-const transformFunctionName = (v) => {
-  v = transformMethodNamesToGo(v)
-  return v[0].toUpperCase() + v.slice(1)
-}
-
 const allowedMissing = [
   "BrowserType.Connect",
   "BrowserType.LaunchServer",
@@ -31,8 +26,8 @@ const allowedMissing = [
 const missingFunctions = []
 
 for (const [className, classData] of Object.entries(api).filter(shouldIgnoreClass)) {
-  for (const [funcName, funcData] of Object.entries(classData.methods)) {
-    const goFuncName = transformFunctionName(funcName)
+  for (const funcName in classData.methods) {
+    const goFuncName = transformMethodNamesToGo(funcName)
     const functionSignature = `${className}.${goFuncName}`;
     if (!interfaceData[className] || !interfaceData[className][goFuncName] && !allowedMissing.includes(functionSignature)) {
       missingFunctions.push(functionSignature)
@@ -42,6 +37,6 @@ for (const [className, classData] of Object.entries(api).filter(shouldIgnoreClas
 
 if (missingFunctions.length > 0) {
   console.log("Missing API interface functions:")
-  console.log(missingFunctions.map(item => `- ${item}`).join("\n"))
+  console.log(missingFunctions.map(item => `- [ ] ${item}`).join("\n"))
   process.exit(1)
 }