Add docs for conversations 2.0 (#1147)

Co-authored-by: Roj <[email protected]> Co-authored-by: Roj <[email protected]> Co-authored-by: Qz <[email protected]> Co-authored-by: Mased <[email protected]> Co-authored-by: Nazar Antoniuk <[email protected]> Co-authored-by: Habemuscode <[email protected]> Co-authored-by: Andrii Zontov <[email protected]> Co-authored-by: deptyped <[email protected]> Co-authored-by: agoudbg <[email protected]> Co-authored-by: Acer <>
grammyjs · Feb 1, 2025 · f644208 · f644208
1 parent 8b67acd
commit f644208
Show file tree

Hide file tree

Showing 29 changed files with 7,169 additions and 4,988 deletions.
diff --git a/site/api/components/Class.tsx b/site/api/components/Class.tsx
@@ -72,11 +72,13 @@ export function Class(
 
   const methodNameSet = new Set<string>(); // to prevent duplicates
   const staticMethodNameSet = new Set<string>();
+  const anchors = methods.map((v) => v.name)
+    .concat(staticMethods.map((v) => v.name));
 
   return (
     <>
       <H1>{klass.name}</H1>
-      <P doc>{klass.jsDoc?.doc}</P>
+      <P doc getLink={getLink} anchors={anchors}>{klass.jsDoc?.doc}</P>
       <Loc>{klass}</Loc>
       <Sector title="Extends" show={!!klass.classDef.extends}>
         <CodeBlock>

diff --git a/site/api/components/Class/Constructors.tsx b/site/api/components/Class/Constructors.tsx
@@ -29,7 +29,7 @@ export function Constructors({
             </span>(
             <Params getLink={getLink}>{v.params}</Params>);
           </CodeBlock>
-          {"jsDoc" in v && <P doc>{v.jsDoc?.doc}</P>}
+          {"jsDoc" in v && <P doc getLink={getLink}>{v.jsDoc?.doc}</P>}
           <Loc>{v}</Loc>
         </>
       ))}

diff --git a/site/api/components/Class/Method.tsx b/site/api/components/Class/Method.tsx
@@ -48,7 +48,7 @@ export function Method({
             </>
           ))}
       </CodeBlock>
-      <P doc>{jsDoc?.doc}</P>
+      <P doc getLink={getLink}>{jsDoc?.doc}</P>
       <Loc>{method}</Loc>
     </>
   );

diff --git a/site/api/components/Function.tsx b/site/api/components/Function.tsx
@@ -28,7 +28,7 @@ export function Function(
   return (
     <>
       {(!overloadCount || overloadCount == 1) && <H1>{func.name}</H1>}
-      {overloadCount && <P doc>{func.jsDoc?.doc}</P>}
+      {overloadCount && <P doc getLink={getLink}>{func.jsDoc?.doc}</P>}
       {!!overloads?.length && (
         <CodeBlock>
           //{" "}
@@ -65,7 +65,7 @@ export function Function(
         </CodeBlock>
       )}
       {overloadCount && <H2>Overload {overloadCount}</H2>}
-      {!overloadCount && <P doc>{func.jsDoc?.doc}</P>}
+      {!overloadCount && <P doc getLink={getLink}>{func.jsDoc?.doc}</P>}
       <Loc>{func}</Loc>
       <Sector
         title="Type Parameters"

diff --git a/site/api/components/Function/Parameters.tsx b/site/api/components/Function/Parameters.tsx
@@ -59,7 +59,7 @@ export function Parameters(
           <CodeBlock>
             <Param getLink={getLink}>{v}</Param>
           </CodeBlock>
-          <P doc>
+          <P doc getLink={getLink}>
             {doc?.tags?.find((v_): v_ is JsDocTagParam =>
               v_.kind == "param" && v_.name == getTitle(v)
             )?.doc}

diff --git a/site/api/components/Function/ReturnType.tsx b/site/api/components/Function/ReturnType.tsx
@@ -16,7 +16,7 @@ export function ReturnType(
       <CodeBlock>
         <TsType getLink={getLink}>{ret}</TsType>
       </CodeBlock>
-      <P doc>
+      <P doc getLink={getLink}>
         {doc?.tags?.find((v): v is JsDocTagReturn => v.kind == "return")?.doc}
       </P>
     </>

diff --git a/site/api/components/Indexes.tsx b/site/api/components/Indexes.tsx
@@ -0,0 +1,70 @@
+import {
+  InterfaceIndexSignatureDef,
+  ParamIdentifierDef,
+} from "@deno/doc/types";
+import { PropertyName } from "./PropertyName.tsx";
+import { TsType } from "./TsType.tsx";
+import { LinkGetter } from "./types.ts";
+import { H3 } from "./H3.tsx";
+import { CodeBlock } from "./CodeBlock.tsx";
+import { P } from "./P.tsx";
+import { StyleKw } from "./styles.tsx";
+import { Loc } from "./Loc.tsx";
+
+export function Indexes({
+  getLink,
+  children: i,
+}: {
+  getLink: LinkGetter;
+  children: InterfaceIndexSignatureDef[];
+}) {
+  return (
+    <>
+      {i.filter((v) =>
+        "accessiblity" in v ? v.accessiblity !== "private" : true
+      )
+        .map((v) => (
+          <>
+            <H3>
+              [{(v.params[0] as ParamIdentifierDef).name}:{" "}
+              {v.params[0].tsType?.repr}]
+            </H3>
+            <CodeBlock>
+              {"isStatic" in v && v.isStatic && <StyleKw>{"static "}</StyleKw>}
+              {"isAbstract" in v && v.isAbstract && (
+                <StyleKw>{"abstract "}</StyleKw>
+              )}
+              {v.readonly && <StyleKw>{"readonly "}</StyleKw>}
+              <PropertyName hasType={!!v.tsType} class>
+                {{
+                  raw: (
+                    <>
+                      [{(v.params[0] as ParamIdentifierDef).name}
+                      {v.params[0].tsType && (
+                        <>
+                          :{" "}
+                          <TsType getLink={getLink}>
+                            {v.params[0].tsType}
+                          </TsType>
+                        </>
+                      )}]
+                    </>
+                  ),
+                }}
+              </PropertyName>
+              {v.tsType && (
+                <>
+                  {" "}
+                  <TsType getLink={getLink}>{v.tsType}</TsType>
+                </>
+              )};
+            </CodeBlock>
+            {/* @ts-ignore: it works */}
+            {"jsDoc" in v && <P doc getLink={getLink}>{v.jsDoc}</P>}
+            {/* @ts-ignore: this works too */}
+            <Loc>{v}</Loc>
+          </>
+        ))}
+    </>
+  );
+}
diff --git a/site/api/components/Interface.tsx b/site/api/components/Interface.tsx
@@ -9,6 +9,7 @@ import { CodeBlock } from "./CodeBlock.tsx";
 import { TsType } from "./TsType.tsx";
 import { ToC } from "./ToC.tsx";
 import { Method } from "./Class/Method.tsx";
+import { Indexes } from "./Indexes.tsx";
 
 export function Interface(
   { children: iface, getLink, namespace }: {
@@ -19,6 +20,7 @@ export function Interface(
 ) {
   const props = iface.interfaceDef.properties;
   const methods = iface.interfaceDef.methods;
+  const indexes = iface.interfaceDef.indexSignatures;
   const methodNameSet = new Set<string>(); // to prevent duplicates
 
   const getMethodOverloads = (name: string) => {
@@ -28,7 +30,7 @@ export function Interface(
   return (
     <>
       <H1>{iface.name}</H1>
-      <P doc>{iface.jsDoc?.doc}</P>
+      <P doc getLink={getLink}>{iface.jsDoc?.doc}</P>
       <Loc>{iface}</Loc>
       <Sector title="Extends" show={!!iface.interfaceDef.extends.length}>
         <CodeBlock>
@@ -43,6 +45,9 @@ export function Interface(
       <Sector title="Properties" show={!!props.length}>
         <Properties getLink={getLink}>{props}</Properties>
       </Sector>
+      <Sector title="Indexes" show={!!indexes.length}>
+        <Indexes getLink={getLink}>{indexes}</Indexes>
+      </Sector>
       <Sector title="Methods" show={!!methods.length}>
         {methods
           .filter((v) => {

diff --git a/site/api/components/P.tsx b/site/api/components/P.tsx
@@ -1,9 +1,13 @@
 import { ComponentChildren } from "preact";
+import { replaceModuleSymbolLinks } from "./util.ts";
+import { LinkGetter } from "./types.ts";
 
 export function P(
   props: { children?: ComponentChildren; doc?: false; html?: true } | {
     children?: string;
     doc: true;
+    getLink: LinkGetter;
+    anchors?: string[];
   },
 ) {
   if (props.doc && props.children) {
@@ -28,6 +32,11 @@ export function P(
     props.children = newParts
       .join("")
       .replaceAll("```ts", "```ts:no-line-numbers");
+    props.children = replaceModuleSymbolLinks(
+      props.children,
+      props.getLink,
+      props.anchors,
+    );
     return (
       <>
         {"\n\n"}

diff --git a/site/api/components/Properties.tsx b/site/api/components/Properties.tsx
@@ -37,7 +37,7 @@ export function Properties({
                 </>
               )};
             </CodeBlock>
-            {"jsDoc" in v && <P doc>{v.jsDoc?.doc}</P>}
+            {"jsDoc" in v && <P doc getLink={getLink}>{v.jsDoc?.doc}</P>}
             <Loc>{v}</Loc>
           </>
         ))}

diff --git a/site/api/components/PropertyName.tsx b/site/api/components/PropertyName.tsx
@@ -1,16 +1,18 @@
 export function PropertyName({
-  children: { name, optional },
+  children,
   hasType,
   "class": klass,
 }: {
-  children: { name: string; optional: boolean };
+  // deno-lint-ignore no-explicit-any
+  children: { name: string; optional: boolean } | { raw: any };
   hasType: boolean;
   class?: true;
 }) {
+  const optional = "raw" in children ? false : children.optional;
   return (
     <>
       <span style={klass ? "" : "--shiki-light:#24292E;--shiki-dark:#E1E4E8;"}>
-        {name}
+        {"raw" in children ? children.raw : children.name}
       </span>
       {(optional || hasType) && (
         <span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">

diff --git a/site/api/components/TsType.tsx b/site/api/components/TsType.tsx
@@ -677,9 +677,16 @@ function ParamArray({
   optional: boolean;
   getLink: LinkGetter;
 }) {
+  const elements = param.elements.map((e) =>
+    e && <Param getLink={getLink}>{e}</Param>
+  );
+  let elementsElement: JSX.Element | undefined;
+  if (elements.length) {
+    elementsElement = elements.reduce((a, b) => <>{a}, {b}</>);
+  }
   return (
     <>
-      [{param.elements.map((e) => e && <Param getLink={getLink}>{e}</Param>)}]
+      [{elementsElement || elements}]
       {param.optional || optional ? "?" : ""}
       {param.tsType && (
         <>

diff --git a/site/api/components/TypeAlias.tsx b/site/api/components/TypeAlias.tsx
@@ -21,7 +21,7 @@ export function TypeAlias(
   return (
     <>
       <H1>{typeAlias.name}</H1>
-      <P doc>{typeAlias.jsDoc?.doc}</P>
+      <P doc getLink={getLink}>{typeAlias.jsDoc?.doc}</P>
       <Loc>{typeAlias}</Loc>
       <Sector title="Type Parameters" show={!!typeParams.length}>
         <TypeParams getLink={getLink}>{typeParams}</TypeParams>

diff --git a/site/api/components/Variable.tsx b/site/api/components/Variable.tsx
@@ -16,7 +16,7 @@ export function Variable(
   return (
     <>
       <H1>{varr.name}</H1>
-      <P doc>{varr.jsDoc?.doc}</P>
+      <P doc getLink={getLink}>{varr.jsDoc?.doc}</P>
       <Loc>{varr}</Loc>
       <Sector title="Type" show={!!varr.variableDef.tsType}>
         <CodeBlock>

diff --git a/site/api/components/util.ts b/site/api/components/util.ts
@@ -1,4 +1,5 @@
 import { TsTypeParamDef } from "@deno/doc/types";
+import { LinkGetter } from "./types.ts";
 
 export function newGetLink(
   oldGetLink: (r: string) => string | null,
@@ -14,3 +15,85 @@ export function newGetLink(
     return l;
   };
 }
+
+export function replaceModuleSymbolLinks(
+  text: string,
+  getLink: LinkGetter,
+  anchors: string[] | undefined,
+) {
+  return replaceSymbolLinks(text, (match) => {
+    let [link, text = ""] = match.split("|");
+    text = text.trim();
+    const [symbol, anchor] = link.trim().split(".");
+    let href: string;
+    if (anchors?.includes(symbol)) {
+      href = `#${symbol}`;
+    } else {
+      href = getLink(symbol) ?? "";
+      if (anchor) {
+        href += `#${anchor}`;
+      }
+    }
+    href = href.toLowerCase();
+    return `[${text || match}](${href})`;
+  });
+}
+function replaceSymbolLinks(
+  text: string,
+  replacer: (string: string) => string,
+) {
+  let newText = "";
+  let stackActive = false;
+  let stackExpects: "keyword" | "value" = "keyword";
+  let stack = new Array<string>();
+  let value = "";
+
+  const flushStack = () => {
+    stackExpects = "keyword";
+    stackActive = false;
+    value = "";
+    for (const item of stack) {
+      newText += item;
+    }
+    stack = [];
+  };
+
+  for (let i = 0; i < text.length; ++i) {
+    const char = text[i];
+    const prevChar = text[i - 1] || "";
+    if (char == "{" && prevChar != "\\") {
+      stackActive = true;
+      stack.push(char);
+      continue;
+    }
+    if (stackActive) {
+      stack.push(char);
+    } else {
+      newText += char;
+    }
+    if (stackActive && stackExpects == "keyword") {
+      if (/\s/.test(char)) {
+        continue;
+      }
+      if (text.slice(i, i + "@link ".length) != "@link ") {
+        flushStack();
+      } else {
+        stackExpects = "value";
+        i += "@link ".length - 1;
+        continue;
+      }
+    }
+    if (stackExpects == "value" && char == "}" && prevChar != "\\") {
+      value = value.trim();
+      newText += replacer(value);
+      stack = [];
+      flushStack();
+      continue;
+    }
+    if (stackExpects == "value") {
+      value += char;
+    }
+  }
+
+  return newText;
+}