@alloy-js/csharp 0.18.0-dev.18 → 0.18.0-dev.2

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

@@ -1,337 +0,0 @@
-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

@@ -1,152 +0,0 @@
-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

@@ -1,103 +0,0 @@
-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

@@ -1,58 +0,0 @@
-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;
-  }
-}