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

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

@@ -0,0 +1,337 @@
+import { describe, expect, it } from "vitest";
+import {
+  DocC,
+  DocCode,
+  DocComment,
+  DocDescription,
+  DocExample,
+  DocException,
+  DocInclude,
+  DocList,
+  DocPara,
+  DocParam,
+  DocParamRef,
+  DocPermission,
+  DocRemarks,
+  DocReturns,
+  DocSee,
+  DocSeeAlso,
+  DocSummary,
+  DocTypeParam,
+  DocTypeParamRef,
+  DocValue,
+} from "./comment.jsx";
+
+it("define summary", () => {
+  expect(
+    <DocComment>
+      <DocSummary>This is a sample doc comment</DocSummary>
+    </DocComment>,
+  ).toRenderTo(`
+    /// <summary>
+    /// This is a sample doc comment
+    /// </summary>
+  `);
+});
+
+it("define code", () => {
+  expect(
+    <DocComment>
+      <DocCode>code sample</DocCode>
+    </DocComment>,
+  ).toRenderTo(`
+    /// <code>
+    /// code sample
+    /// </code>
+  `);
+});
+
+it("define c", () => {
+  expect(
+    <DocComment>
+      <DocC>inline code</DocC>
+    </DocComment>,
+  ).toRenderTo(`
+    /// <c>inline code</c>
+  `);
+});
+
+it("define example", () => {
+  expect(
+    <DocComment>
+      <DocExample>example usage</DocExample>
+    </DocComment>,
+  ).toRenderTo(`
+    /// <example>
+    /// example usage
+    /// </example>
+  `);
+});
+
+it("define exception", () => {
+  expect(
+    <DocComment>
+      <DocException>exception info</DocException>
+    </DocComment>,
+  ).toRenderTo(`
+    /// <exception>
+    /// exception info
+    /// </exception>
+  `);
+});
+
+it("define include", () => {
+  expect(
+    <DocComment>
+      <DocInclude file="external.xml" path="/doc/summary" />
+    </DocComment>,
+  ).toRenderTo(`
+    /// <include file="external.xml" path="/doc/summary" />
+  `);
+});
+
+it("define param", () => {
+  expect(
+    <DocComment>
+      <DocParam name="x">parameter x</DocParam>
+    </DocComment>,
+  ).toRenderTo(`
+    /// <param name="x">parameter x</param>
+  `);
+});
+
+it("define typeparam", () => {
+  expect(
+    <DocComment>
+      <DocTypeParam name="T">type parameter T</DocTypeParam>
+    </DocComment>,
+  ).toRenderTo(`
+    /// <typeparam name="T">type parameter T</typeparam>
+  `);
+});
+
+it("define returns", () => {
+  expect(
+    <DocComment>
+      <DocReturns>return value</DocReturns>
+    </DocComment>,
+  ).toRenderTo(`
+    /// <returns>
+    /// return value
+    /// </returns>
+  `);
+});
+
+it("define remarks", () => {
+  expect(
+    <DocComment>
+      <DocRemarks>remarks here</DocRemarks>
+    </DocComment>,
+  ).toRenderTo(`
+    /// <remarks>
+    /// remarks here
+    /// </remarks>
+  `);
+});
+
+it("define value", () => {
+  expect(
+    <DocComment>
+      <DocValue>property value</DocValue>
+    </DocComment>,
+  ).toRenderTo(`
+    /// <value>
+    /// property value
+    /// </value>
+  `);
+});
+
+it("define permission", () => {
+  expect(
+    <DocComment>
+      <DocPermission>permission info</DocPermission>
+    </DocComment>,
+  ).toRenderTo(`
+    /// <permission>
+    /// permission info
+    /// </permission>
+  `);
+});
+
+it("define list", () => {
+  expect(
+    <DocComment>
+      <DocList type="bullet" items={["item 1", "item 2", "item 3"]} />
+    </DocComment>,
+  ).toRenderTo(`
+    /// <list type="bullet">
+    ///   <item><description>item 1</description></item>
+    ///   <item><description>item 2</description></item>
+    ///   <item><description>item 3</description></item>
+    /// </list>
+  `);
+});
+
+it("define description", () => {
+  expect(
+    <DocComment>
+      <DocDescription>description content</DocDescription>
+    </DocComment>,
+  ).toRenderTo(`
+    /// <description>
+    /// description content
+    /// </description>
+  `);
+});
+
+it("define para", () => {
+  expect(
+    <DocComment>
+      <DocPara>paragraph content</DocPara>
+    </DocComment>,
+  ).toRenderTo(`
+    /// <para>
+    /// paragraph content
+    /// </para>
+  `);
+});
+
+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" />
+    `);
+  });
+});
+
+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" />
+    </DocComment>,
+  ).toRenderTo(`
+    /// <paramref name="${"x"}" />
+  `);
+});
+
+it("define typeparamref", () => {
+  expect(
+    <DocComment>
+      <DocTypeParamRef name="T" />
+    </DocComment>,
+  ).toRenderTo(`
+    /// <typeparamref name="T" />
+  `);
+});
+
+it("wrap long summary", () => {
+  expect(
+    <DocComment>
+      <DocSummary>
+        This is a very long sample doc comment that exceeds the typical line
+        length limit and should be wrapped appropriately in the generated
+        documentation.
+      </DocSummary>
+    </DocComment>,
+  ).toRenderTo(`
+    /// <summary>
+    /// This is a very long sample doc comment that exceeds the typical line length limit
+    /// and should be wrapped appropriately in the generated documentation.
+    /// </summary>
+  `);
+});
+
+it("combine multiple tags", () => {
+  expect(
+    <DocComment>
+      <DocSummary>
+        This operator determines whether two Points have the same location.
+      </DocSummary>
+      <DocParam name="p1">The first Point to be compared.</DocParam>
+      <DocParam name="p2">The second Point to be compared.</DocParam>
+      <DocReturns>
+        True if the Points do not have the same location and the exact same
+        type; otherwise, false.
+      </DocReturns>
+      <DocSeeAlso cref="Equals" />
+      <DocSeeAlso cref="operator==" />
+    </DocComment>,
+  ).toRenderTo(`
+    /// <summary>
+    /// This operator determines whether two Points have the same location.
+    /// </summary>
+    /// <param name="p1">The first Point to be compared.</param>
+    /// <param name="p2">The second Point to be compared.</param>
+    /// <returns>
+    /// True if the Points do not have the same location and the exact same type; otherwise,
+    /// false.
+    /// </returns>
+    /// <seealso cref="Equals" />
+    /// <seealso cref="operator==" />
+  `);
+});

package/src/components/doc/comment.tsx

@@ -0,0 +1,152 @@
+import { Children, code, For, Indent, List, Prose, Show } from "@alloy-js/core";
+
+export interface DocCommentProps {
+  children: Children;
+}
+
+export function DocComment(props: DocCommentProps) {
+  return (
+    <>
+      {"/// "}
+      <align string="/// ">
+        <List>{props.children}</List>
+      </align>
+    </>
+  );
+}
+
+export interface DocWhenProps {
+  doc: Children | undefined;
+}
+
+/** Conditionally render the given doc in a <DocComment /> component and tail with a line */
+export function DocWhen(props: DocWhenProps) {
+  return (
+    <Show when={Boolean(props.doc)}>
+      <DocComment children={props.doc} />
+      <hbr />
+    </Show>
+  );
+}
+
+export interface DocCommentTagProps {
+  children: Children;
+}
+
+export function makeDocCommentTag(name: string) {
+  return function DocCommentTag(props: DocCommentProps) {
+    return (
+      <Prose>
+        {code`
+        <${name}>
+        ${props.children}
+        </${name}>`}
+      </Prose>
+    );
+  };
+}
+export function makeInlineDocCommentTag(name: string) {
+  return function DocCommentTag(props: DocCommentProps) {
+    return `<${name}>${props.children}</${name}>`;
+  };
+}
+
+export const DocSummary = makeDocCommentTag("summary");
+export const DocCode = makeDocCommentTag("code");
+export const DocC = makeInlineDocCommentTag("c");
+export const DocExample = makeDocCommentTag("example");
+export const DocException = makeDocCommentTag("exception");
+
+export interface DocIncludeProps {
+  /**  is the file name of an external XML file. The file name is interpreted relative to the file that contains the include tag. */
+  file: string;
+  /** is an XPath expression that selects some of the XML in the external XML file. */
+  path?: string;
+}
+export const DocInclude = (props: DocIncludeProps) => {
+  return `<include file="${props.file}" path="${props.path}" />`;
+};
+
+export interface DocParamProps {
+  name: string;
+  children: Children;
+}
+export const DocParam = (props: DocParamProps) =>
+  code`<param name="${props.name}">${props.children}</param>`;
+
+export interface DocTypeParamProps {
+  name: string;
+  children: Children;
+}
+export const DocTypeParam = (props: DocTypeParamProps) =>
+  code`<typeparam name="${props.name}">${props.children}</typeparam>`;
+
+export const DocReturns = makeDocCommentTag("returns");
+export const DocRemarks = makeDocCommentTag("remarks");
+export const DocValue = makeDocCommentTag("value");
+export const DocPermission = makeDocCommentTag("permission");
+export const DocDescription = makeDocCommentTag("description");
+export const DocPara = makeDocCommentTag("para");
+
+export interface DocSeeProps {
+  cref?: string;
+  href?: string;
+  langword?: string;
+  children?: Children;
+}
+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;
+  href?: string;
+  children?: Children;
+}
+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;
+}
+export const DocParamRef = (props: DocParamRefProps) =>
+  `<paramref name="${props.name}" />`;
+
+export interface DocTypeParamRefProps {
+  name: string;
+}
+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";

package/src/components/interface/declaration.test.tsx

@@ -43,3 +43,14 @@ describe("modifiers", () => {
     `);
   });
 });
+
+it("specify doc comment", () => {
+  expect(
+    <TestNamespace>
+      <InterfaceDeclaration name="TestInterface" doc="This is a test" />
+    </TestNamespace>,
+  ).toRenderTo(`
+    /// This is a test
+    interface TestInterface;
+  `);
+});

package/src/components/interface/declaration.tsx

@@ -8,6 +8,7 @@ import {
 import { useCSharpNamePolicy } from "../../name-policy.js";
 import { CSharpOutputSymbol } from "../../symbols/csharp-output-symbol.js";
 import { CSharpMemberScope } from "../../symbols/scopes.js";
+import { DocWhen } from "../doc/comment.jsx";
 import { Name } from "../Name.jsx";
 
 export interface InterfaceModifiers {
@@ -22,6 +23,9 @@ export interface InterfaceDeclarationProps
     AccessModifiers,
     InterfaceModifiers {
   name: string;
+
+  /** Doc comment */
+  doc?: core.Children;
   refkey?: core.Refkey;
   typeParameters?: Record<string, core.Refkey>;
 }
@@ -92,6 +96,7 @@ export function InterfaceDeclaration(props: InterfaceDeclarationProps) {
   ]);
   return (
     <core.Declaration symbol={thisInterfaceSymbol}>
+      <DocWhen doc={props.doc} />
       {modifiers}interface <Name />
       {typeParams}
       {props.children ?