docs: link types

wevm · Oct 23, 2024 · fb9be51 · fb9be51
1 parent b7f293e
commit fb9be51
Show file tree

Hide file tree

Showing 7 changed files with 74 additions and 22 deletions.
diff --git a/scripts/docgen/build.ts b/scripts/docgen/build.ts
@@ -47,13 +47,13 @@ const moduleDocComments = extractNamespaceDocComments(
 )
 
 const testNamespaces: string[] = []
+const excludeNamespaces = ['Caches', 'Constants', 'Internal', 'Types']
 const namespaces = []
 const glossaryNamespaces = []
 for (const member of apiEntryPoint.members) {
   if (member.kind !== model.ApiItemKind.Namespace) continue
   if (!namespaceRegex.test(getId(member))) continue
-  if (['Caches', 'Constants', 'Internal', 'Types'].includes(member.displayName))
-    continue
+  if (excludeNamespaces.includes(member.displayName)) continue
   if (testNamespaces.length && !testNamespaces.includes(member.displayName))
     continue
   if (['Errors'].includes(member.displayName)) glossaryNamespaces.push(member)
@@ -229,8 +229,6 @@ fs.writeFileSync(
 let content = '# API Reference\n\n'
 
 content += '<table className="vocs_Table">\n'
-content +=
-  '<thead><tr><th className="vocs_TableHeader">Name</th><th className="vocs_TableHeader">Description</th></tr></thead>\n'
 content += '<tbody>\n'
 
 for (const [category, items] of alphabetizedNamespaceMap) {

diff --git a/scripts/docgen/render/apiFunction.ts b/scripts/docgen/render/apiFunction.ts
@@ -31,10 +31,11 @@ export function renderApiFunction(options: {
       }),
     )
 
-  if (data.returnType)
+  if (data.returnType && !data.returnType.type.startsWith('asserts '))
     content.push(
       renderReturnType({
         comment: comment?.returns,
+        dataLookup,
         returnType: data.returnType,
       }),
     )
@@ -62,11 +63,14 @@ function renderImports(options: {
   const content = [
     '## Imports',
     [
-      '```ts twoslash',
-      '// @noErrors',
+      ':::code-group',
+      '```ts twoslash [Named]',
       `import { ${module} } from 'ox'`,
+      '```',
+      '```ts twoslash [Entrypoint]',
       `import * as ${module} from 'ox/${module}'`,
       '```',
+      ':::',
     ].join('\n'),
   ]
   return content.join('\n\n')
@@ -114,13 +118,12 @@ function renderSignature(options: {
     overloads,
     returnType,
   })
-  const signature = `function ${
-    displayName
-  }${genericSignature}(${paramSignature}): ${returnTypeSignature}`
+  const signature = `function ${displayName
+    }${genericSignature}(${paramSignature}): ${returnTypeSignature}`
 
   content.push(`\`\`\`ts\n${signature}\n\`\`\``)
   content.push(
-    `Source: [${data.file.path}](${data.file.url}${data.file.lineNumber ? `#L${data.file.lineNumber}` : ''})`,
+    `**Source:** [${data.file.path}](${data.file.url}${data.file.lineNumber ? `#L${data.file.lineNumber}` : ''})`,
   )
   return content.join('\n\n')
 }
@@ -149,7 +152,12 @@ function renderParameters(options: {
     })
     parameterIndex += 1
 
-    const listContent = [`- **Type:** \`${type}\``]
+    const link = getTypeLink({ dataLookup, type: parameter })
+
+    const c = `\`${type}\``
+    const listContent = link
+      ? [`- **Type:** [${c}](${link})`]
+      : [`- **Type:** ${c}`]
     if (parameter.optional) listContent.push('- **Optional**')
     content.push(listContent.join('\n'))
 
@@ -207,13 +215,30 @@ function renderParameters(options: {
 
 function renderReturnType(options: {
   comment: NonNullable<Data['comment']>['returns'] | undefined
+  dataLookup: Record<string, Data>
   returnType: NonNullable<Data['returnType']>
 }) {
-  const { comment, returnType } = options
+  const { comment, dataLookup, returnType } = options
 
   const content = ['## Return Type']
   if (comment) content.push(comment)
-  content.push(`\`${returnType.type}\``)
+  const link = getTypeLink({ dataLookup, type: returnType })
+  const type = (() => {
+    // expand inline type to include namespace (e.g. `Address` => `Address.Address`)
+    const expandRegex = /^ox!(?<type>.+)(_2):type/
+    if (
+      returnType.primaryCanonicalReference &&
+      expandRegex.test(returnType.primaryCanonicalReference) &&
+      !returnType.primaryGenericArguments
+    ) {
+      const type =
+        returnType.primaryCanonicalReference.match(expandRegex)?.groups?.type
+      return type
+    }
+    return returnType.type
+  })()
+  const c = `\`${type}\``
+  content.push(link ? `[${c}](${link})` : c)
 
   return content.join('\n\n')
 }
@@ -276,6 +301,18 @@ function resolveInlineParameterTypeForOverloads(options: {
         ) ?? parameter.type
       )
   }
+
+  // expand inline type to include namespace (e.g. `Address` => `Address.Address`)
+  const expandRegex = /^ox!(?<type>.+)(_2):type/
+  if (
+    parameter.primaryCanonicalReference &&
+    expandRegex.test(parameter.primaryCanonicalReference) &&
+    !parameter.primaryGenericArguments
+  ) {
+    const type =
+      parameter.primaryCanonicalReference.match(expandRegex)?.groups?.type
+    return type
+  }
   return parameter.type
 }
 
@@ -334,3 +371,23 @@ function resolveErrorData(options: {
 
   return errors
 }
+
+function getTypeLink(options: {
+  dataLookup: Record<string, Data>
+  type: Pick<
+    NonNullable<Data['returnType']>,
+    'primaryCanonicalReference' | 'primaryGenericArguments'
+  >
+}) {
+  const { dataLookup, type } = options
+  if (type.primaryCanonicalReference && !type.primaryGenericArguments) {
+    const data =
+      dataLookup[type.primaryCanonicalReference] ??
+      dataLookup[type.primaryCanonicalReference.replace('_2', '')]
+    if (!data) return
+
+    const displayNameWithNamespace = `${data.module}.${data.displayName}`
+    return `/api/${data.module}/types#${displayNameWithNamespace.toLowerCase().replace('.', '')}`
+  }
+  return
+}
diff --git a/scripts/docgen/render/apiNamespace.ts b/scripts/docgen/render/apiNamespace.ts
@@ -107,7 +107,7 @@ export function renderNamespaceErrors(options: {
       }
     }
     content.push(
-      `Source: [${data.file.path}](${data.file.url}${data.file.lineNumber ? `#L${data.file.lineNumber}` : ''})`,
+      `**Source:** [${data.file.path}](${data.file.url}${data.file.lineNumber ? `#L${data.file.lineNumber}` : ''})`,
     )
   }
 
@@ -140,7 +140,7 @@ export function renderNamespaceTypes(options: {
       }
     }
     content.push(
-      `Source: [${data.file.path}](${data.file.url}${data.file.lineNumber ? `#L${data.file.lineNumber}` : ''})`,
+      `**Source:** [${data.file.path}](${data.file.url}${data.file.lineNumber ? `#L${data.file.lineNumber}` : ''})`,
     )
   }
 

diff --git a/src/internal/Address/assert.ts b/src/internal/Address/assert.ts
@@ -1,4 +1,5 @@
 import type { GlobalErrorType } from '../Errors/error.js'
+import { addressRegex } from '../regex.js'
 import { Address_checksum } from './checksum.js'
 import {
   Address_InvalidAddressError,
@@ -7,8 +8,6 @@ import {
 } from './errors.js'
 import type { Address } from './types.js'
 
-const addressRegex = /^0x[a-fA-F0-9]{40}$/
-
 /**
  * Asserts that the given value is a valid {@link ox#Address.Address}.
  *

diff --git a/src/internal/Address/from.ts b/src/internal/Address/from.ts
@@ -25,9 +25,6 @@ import type { Address } from './types.js'
  * ```
  *
  * @example
- *
- * Do something with {@link ox#Address.Address}.
- *
  * ```ts twoslash
  * import { Address } from 'ox'
  *

diff --git a/src/internal/Address/fromPublicKey.ts b/src/internal/Address/fromPublicKey.ts
@@ -24,7 +24,7 @@ import type { Address } from './types.js'
  * @returns The {@link ox#Address.Address}.
  */
 export function Address_fromPublicKey(
-  publicKey: PublicKey<false>,
+  publicKey: PublicKey,
   options: Address_fromPublicKey.Options = {},
 ): Address {
   const address = Hash_keccak256(

diff --git a/src/internal/regex.ts b/src/internal/regex.ts
@@ -0,0 +1 @@
+export const addressRegex = /^0x[a-fA-F0-9]{40}$/
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		export const addressRegex = /^0x[a-fA-F0-9]{40}$/