@alloy-js/csharp 0.18.0-dev.8 → 0.18.0-dev.9

package/src/components/doc/comment.test.tsx

@@ -1,26 +1,22 @@
-import { expect, it } from "vitest";
+import { describe, expect, it } from "vitest";
 import {
   DocC,
   DocCode,
   DocComment,
-  DocCompletionList,
   DocDescription,
   DocExample,
   DocException,
   DocInclude,
-  DocItem,
   DocList,
   DocPara,
   DocParam,
   DocParamRef,
   DocPermission,
   DocRemarks,
-  DocResponse,
   DocReturns,
   DocSee,
   DocSeeAlso,
   DocSummary,
-  DocTerm,
   DocTypeParam,
   DocTypeParamRef,
   DocValue,
@@ -56,9 +52,7 @@ it("define c", () => {
       <DocC>inline code</DocC>
     </DocComment>,
   ).toRenderTo(`
-    /// <c>
-    /// inline code
-    /// </c>
+    /// <c>inline code</c>
   `);
 });
 
@@ -89,7 +83,7 @@ it("define exception", () => {
 it("define include", () => {
   expect(
     <DocComment>
-      <>{DocInclude({ file: "external.xml", path: "/doc/summary" })}</>
+      <DocInclude file="external.xml" path="/doc/summary" />
     </DocComment>,
   ).toRenderTo(`
     /// <include file="external.xml" path="/doc/summary" />
@@ -164,66 +158,20 @@ it("define permission", () => {
   `);
 });
 
-it("define response", () => {
-  expect(
-    <DocComment>
-      <DocResponse>response info</DocResponse>
-    </DocComment>,
-  ).toRenderTo(`
-    /// <response>
-    /// response info
-    /// </response>
-  `);
-});
-
-it("define completionlist", () => {
-  expect(
-    <DocComment>
-      <DocCompletionList>completion list</DocCompletionList>
-    </DocComment>,
-  ).toRenderTo(`
-    /// <completionlist>
-    /// completion list
-    /// </completionlist>
-  `);
-});
-
 it("define list", () => {
   expect(
     <DocComment>
-      <DocList>list content</DocList>
+      <DocList type="bullet" items={["item 1", "item 2", "item 3"]} />
     </DocComment>,
   ).toRenderTo(`
-    /// <list>
-    /// list content
+    /// <list type="bullet">
+    ///   <item><description>item 1</description></item>
+    ///   <item><description>item 2</description></item>
+    ///   <item><description>item 3</description></item>
     /// </list>
   `);
 });
 
-it("define item", () => {
-  expect(
-    <DocComment>
-      <DocItem>item content</DocItem>
-    </DocComment>,
-  ).toRenderTo(`
-    /// <item>
-    /// item content
-    /// </item>
-  `);
-});
-
-it("define term", () => {
-  expect(
-    <DocComment>
-      <DocTerm>term content</DocTerm>
-    </DocComment>,
-  ).toRenderTo(`
-    /// <term>
-    /// term content
-    /// </term>
-  `);
-});
-
 it("define description", () => {
   expect(
     <DocComment>
@@ -248,40 +196,93 @@ it("define para", () => {
   `);
 });
 
-it("define see", () => {
-  expect(
-    <DocComment>
-      <>{DocSee({ cref: "T:MyType" })}</>
-    </DocComment>,
-  ).toRenderTo(`
-    /// <see cref="T:MyType" />
-  `);
+describe("define see", () => {
+  it("with cref", () => {
+    expect(
+      <DocComment>
+        <DocSee cref="T:MyType" />
+      </DocComment>,
+    ).toRenderTo(`
+      /// <see cref="T:MyType" />
+    `);
+  });
+
+  it("with href", () => {
+    expect(
+      <DocComment>
+        <DocSee href="https://github.com" />
+      </DocComment>,
+    ).toRenderTo(`
+      /// <see href="https://github.com" />
+    `);
+  });
+  it("with href and children", () => {
+    expect(
+      <DocComment>
+        <DocSee href="https://github.com">GitHub</DocSee>
+      </DocComment>,
+    ).toRenderTo(`
+      /// <see href="https://github.com">GitHub</see>
+    `);
+  });
+
+  it("with langword", () => {
+    expect(
+      <DocComment>
+        <DocSee langword="keyword" />
+      </DocComment>,
+    ).toRenderTo(`
+      /// <see langword="keyword" />
+    `);
+  });
 });
 
-it("define seealso", () => {
-  expect(
-    <DocComment>
-      <>{DocSeeAlso({ cref: "T:OtherType" })}</>
-    </DocComment>,
-  ).toRenderTo(`
-    /// <seealso cref="T:OtherType" />
-  `);
+describe("define seealso", () => {
+  it("with cref", () => {
+    expect(
+      <DocComment>
+        <DocSeeAlso cref="T:OtherType" />
+      </DocComment>,
+    ).toRenderTo(`
+      /// <seealso cref="T:OtherType" />
+    `);
+  });
+
+  it("with href", () => {
+    expect(
+      <DocComment>
+        <DocSeeAlso href="https://github.com" />
+      </DocComment>,
+    ).toRenderTo(`
+      /// <seealso href="https://github.com" />
+    `);
+  });
+
+  it("with children", () => {
+    expect(
+      <DocComment>
+        <DocSeeAlso cref="T:OtherType">OtherType</DocSeeAlso>
+      </DocComment>,
+    ).toRenderTo(`
+      /// <seealso cref="T:OtherType">OtherType</seealso>
+    `);
+  });
 });
 
 it("define paramref", () => {
   expect(
     <DocComment>
-      <>{DocParamRef({ name: "x" })}</>
+      <DocParamRef name="x" />
     </DocComment>,
   ).toRenderTo(`
-    /// <paramref name="x" />
+    /// <paramref name="${"x"}" />
   `);
 });
 
 it("define typeparamref", () => {
   expect(
     <DocComment>
-      <>{DocTypeParamRef({ name: "T" })}</>
+      <DocTypeParamRef name="T" />
     </DocComment>,
   ).toRenderTo(`
     /// <typeparamref name="T" />

package/src/components/doc/comment.tsx

@@ -1,4 +1,4 @@
-import { Children, code, List, Prose, Show } from "@alloy-js/core";
+import { Children, code, For, Indent, List, Prose, Show } from "@alloy-js/core";
 
 export interface DocCommentProps {
   children: Children;
@@ -53,7 +53,7 @@ export function makeInlineDocCommentTag(name: string) {
 
 export const DocSummary = makeDocCommentTag("summary");
 export const DocCode = makeDocCommentTag("code");
-export const DocC = makeDocCommentTag("c");
+export const DocC = makeInlineDocCommentTag("c");
 export const DocExample = makeDocCommentTag("example");
 export const DocException = makeDocCommentTag("exception");
 
@@ -85,29 +85,40 @@ export const DocReturns = makeDocCommentTag("returns");
 export const DocRemarks = makeDocCommentTag("remarks");
 export const DocValue = makeDocCommentTag("value");
 export const DocPermission = makeDocCommentTag("permission");
-export const DocResponse = makeDocCommentTag("response");
-export const DocCompletionList = makeDocCommentTag("completionlist");
-export const DocList = makeDocCommentTag("list");
-export const DocItem = makeDocCommentTag("item");
-export const DocTerm = makeDocCommentTag("term");
 export const DocDescription = makeDocCommentTag("description");
 export const DocPara = makeDocCommentTag("para");
 
 export interface DocSeeProps {
-  cref: string;
+  cref?: string;
+  href?: string;
   langword?: string;
   children?: Children;
 }
-export const DocSee = (props: DocSeeProps) =>
-  `<see cref="${props.cref}"${props.langword ? ` langword="${props.langword}"` : ""}${props.children ? `>${props.children}</see>` : " />"}`;
+export const DocSee = (props: DocSeeProps) => {
+  const attributes = [
+    props.cref ? `cref="${props.cref}"` : undefined,
+    props.href ? `href="${props.href}"` : undefined,
+    props.langword ? `langword="${props.langword}"` : undefined,
+  ]
+    .filter(Boolean)
+    .join(" ");
+  return code`<see ${attributes}${props.children ? code`>${props.children}</see>` : " />"}`;
+};
 
 export interface DocSeeAlsoProps {
-  cref: string;
-  langword?: string;
+  cref?: string;
+  href?: string;
   children?: Children;
 }
-export const DocSeeAlso = (props: DocSeeAlsoProps) =>
-  `<seealso cref="${props.cref}"${props.langword ? ` langword="${props.langword}"` : ""}${props.children ? `>${props.children}</seealso>` : " />"}`;
+export const DocSeeAlso = (props: DocSeeAlsoProps) => {
+  const attributes = [
+    props.cref ? `cref="${props.cref}"` : undefined,
+    props.href ? `href="${props.href}"` : undefined,
+  ]
+    .filter(Boolean)
+    .join(" ");
+  return code`<seealso ${attributes}${props.children ? code`>${props.children}</seealso>` : " />"}`;
+};
 
 export interface DocParamRefProps {
   name: string;
@@ -120,3 +131,22 @@ export interface DocTypeParamRefProps {
 }
 export const DocTypeParamRef = (props: DocTypeParamRefProps) =>
   `<typeparamref name="${props.name}" />`;
+
+export interface DocListProps {
+  type?: "bullet" | "number";
+  items: Children[];
+}
+export function DocList(props: DocListProps) {
+  return (
+    <Prose>
+      {`<list type="${props.type ?? "bullet"}">`}
+      <Indent>
+        <For each={props.items}>
+          {(item) => code`<item><description>${item}</description></item>`}
+        </For>
+      </Indent>
+      <hbr />
+      {`</list>`}
+    </Prose>
+  );
+}

package/src/components/doc/from-markdown.test.tsx

@@ -0,0 +1,103 @@
+import { d } from "@alloy-js/core/testing";
+import { describe, expect, it } from "vitest";
+import { DocFromMarkdown } from "./from-markdown.jsx";
+
+it("convert code block to <code>", () => {
+  expect(
+    <DocFromMarkdown
+      markdown={d`
+        Some markdown with code
+        \`\`\`csharp
+        var foo = "bar";
+        \`\`\`
+    `}
+    />,
+  ).toRenderTo(`
+    Some markdown with code
+    <code>
+    var foo = "bar";
+    </code>
+  `);
+});
+
+it("convert inline code block to <c>", () => {
+  expect(
+    <DocFromMarkdown
+      markdown={d`
+        Some markdown with \`inline\` code
+    `}
+    />,
+  ).toRenderTo(`
+    Some markdown with <c>inline</c> code
+  `);
+});
+
+it("convert link to <see>", () => {
+  expect(
+    <DocFromMarkdown
+      markdown={d`
+        Some markdown with [link](https://example.com)
+    `}
+    />,
+  ).toRenderTo(`
+    Some markdown with <see href="https://example.com">link</see>
+  `);
+});
+
+it("convert bullet list to <list>", () => {
+  expect(
+    <DocFromMarkdown
+      markdown={d`
+        - Item 1
+        - Item 2
+        - Item 3
+    `}
+    />,
+  ).toRenderTo(`
+    <list type="bullet">
+      <item><description>Item 1</description></item>
+      <item><description>Item 2</description></item>
+      <item><description>Item 3</description></item>
+    </list>
+  `);
+});
+
+it("convert numbered list to <list>", () => {
+  expect(
+    <DocFromMarkdown
+      markdown={d`
+        1. Item 1
+        2. Item 2
+        3. Item 3
+    `}
+    />,
+  ).toRenderTo(`
+    <list type="number">
+      <item><description>Item 1</description></item>
+      <item><description>Item 2</description></item>
+      <item><description>Item 3</description></item>
+    </list>
+  `);
+});
+
+describe("strip unsupported elements", () => {
+  it("bold", () => {
+    expect(
+      <DocFromMarkdown
+        markdown={d`
+        Some markdown with **bold** text
+    `}
+      />,
+    ).toRenderTo(`Some markdown with bold text`);
+  });
+
+  it("italic", () => {
+    expect(
+      <DocFromMarkdown
+        markdown={d`
+        Some markdown with *italic* text
+    `}
+      />,
+    ).toRenderTo(`Some markdown with italic text`);
+  });
+});

package/src/components/doc/from-markdown.tsx

@@ -0,0 +1,58 @@
+import { marked, Tokens, type Token } from "marked";
+import { DocC, DocCode, DocList, DocSee } from "./comment.jsx";
+
+export interface DocFromMarkdownProps {
+  markdown: string;
+}
+
+/** Convert markdown to a Csharp doc comment */
+export function DocFromMarkdown(props: DocFromMarkdownProps) {
+  const tokens = marked.lexer(props.markdown);
+  return renderTokens(tokens);
+}
+
+function renderTokens(tokens: Token[]) {
+  return (
+    <>
+      {tokens.map((token, index) => (
+        <>
+          <DocFromMarkedToken token={token} />
+          {token.type === "paragraph" && index !== tokens.length - 1 && <br />}
+        </>
+      ))}
+    </>
+  );
+}
+
+function DocFromMarkedToken(props: { token: Token }) {
+  const { token } = props;
+  switch (token.type) {
+    case "paragraph":
+      return token.tokens ? renderTokens(token.tokens) : null;
+    case "code":
+      return <DocCode>{token.text}</DocCode>;
+    case "codespan":
+      return <DocC>{token.text}</DocC>;
+    case "list":
+      return (
+        <DocList
+          type={token.ordered ? "number" : "bullet"}
+          items={token.items.map((x: Tokens.ListItem) => (
+            <>{renderTokens(x.tokens)}</>
+          ))}
+        />
+      );
+    case "link":
+      return (
+        <DocSee href={token.href}>
+          {token.tokens && renderTokens(token.tokens)}
+        </DocSee>
+      );
+    case "strong":
+    case "em":
+      return token.text;
+    case "text":
+    default:
+      return token.raw;
+  }
+}

package/src/components/index.ts

@@ -1,6 +1,8 @@
 export * from "./ClassDeclaration.jsx";
 export * from "./ClassMethod.jsx";
 export * from "./Declaration.js";
+export * from "./doc/comment.jsx";
+export * from "./doc/from-markdown.jsx";
 export * from "./EnumDeclaration.jsx";
 export * from "./interface/declaration.js";
 export * from "./interface/method.js";