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

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

@@ -0,0 +1,336 @@
+import { 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,
+} 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 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>
+    </DocComment>,
+  ).toRenderTo(`
+    /// <list>
+    /// list content
+    /// </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>
+      <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>
+  `);
+});
+
+it("define see", () => {
+  expect(
+    <DocComment>
+      <>{DocSee({ cref: "T:MyType" })}</>
+    </DocComment>,
+  ).toRenderTo(`
+    /// <see cref="T:MyType" />
+  `);
+});
+
+it("define seealso", () => {
+  expect(
+    <DocComment>
+      <>{DocSeeAlso({ cref: "T:OtherType" })}</>
+    </DocComment>,
+  ).toRenderTo(`
+    /// <seealso cref="T:OtherType" />
+  `);
+});
+
+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,122 @@
+import { Children, code, 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 = makeDocCommentTag("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 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;
+  langword?: string;
+  children?: Children;
+}
+export const DocSee = (props: DocSeeProps) =>
+  `<see cref="${props.cref}"${props.langword ? ` langword="${props.langword}"` : ""}${props.children ? `>${props.children}</see>` : " />"}`;
+
+export interface DocSeeAlsoProps {
+  cref: string;
+  langword?: string;
+  children?: Children;
+}
+export const DocSeeAlso = (props: DocSeeAlsoProps) =>
+  `<seealso cref="${props.cref}"${props.langword ? ` langword="${props.langword}"` : ""}${props.children ? `>${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}" />`;

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 ?

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

@@ -102,3 +102,19 @@ it("defines params and return type", () => {
     }
   `);
 });
+
+it("specify doc comment", () => {
+  expect(
+    <TestNamespace>
+      <InterfaceDeclaration name="Test">
+        <InterfaceMethod name="Method" doc="This is a test" />
+      </InterfaceDeclaration>
+    </TestNamespace>,
+  ).toRenderTo(`
+    interface Test
+    {
+      /// This is a test
+      void Method();
+    }
+  `);
+});

package/src/components/interface/method.tsx

@@ -16,6 +16,7 @@ import { useCSharpNamePolicy } from "../../name-policy.js";
 import { CSharpOutputSymbol } from "../../symbols/csharp-output-symbol.js";
 import { CSharpMemberScope, useCSharpScope } from "../../symbols/scopes.js";
 import { ParameterProps, Parameters } from "../Parameters.jsx";
+import { DocWhen } from "../doc/comment.jsx";
 
 /** Method modifiers. Can only be one. */
 export interface InterfaceMethodModifiers {
@@ -33,6 +34,9 @@ export interface InterfaceMethodProps
   children?: Children;
   parameters?: Array<ParameterProps>;
   returns?: Children;
+
+  /** Doc comment */
+  doc?: Children;
 }
 
 // a C# interface method
@@ -66,6 +70,7 @@ export function InterfaceMethod(props: InterfaceMethodProps) {
   return (
     <MemberDeclaration symbol={methodSymbol}>
       <Scope value={methodScope}>
+        <DocWhen doc={props.doc} />
         {modifiers}
         {props.returns ?? "void"} {name}({params})
         {props.children ?

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

@@ -120,3 +120,25 @@ it("has getter and setter", () => {
     }
   `);
 });
+
+it("specify doc comment", () => {
+  expect(
+    <TestNamespace>
+      <InterfaceDeclaration name="Test">
+        <InterfaceProperty
+          name="Method"
+          type="string"
+          get
+          set
+          doc="This is a test"
+        />
+      </InterfaceDeclaration>
+    </TestNamespace>,
+  ).toRenderTo(`
+    interface Test
+    {
+      /// This is a test
+      string Method { get; set; }
+    }
+  `);
+});

package/src/components/interface/property.tsx

@@ -16,6 +16,7 @@ import {
 import { useCSharpNamePolicy } from "../../name-policy.js";
 import { CSharpOutputSymbol } from "../../symbols/csharp-output-symbol.js";
 import { CSharpMemberScope, useCSharpScope } from "../../symbols/scopes.js";
+import { DocWhen } from "../doc/comment.jsx";
 
 /** Method modifiers. Can only be one. */
 export interface InterfacePropertyModifiers {
@@ -41,6 +42,9 @@ export interface InterfacePropertyProps
 
   /** If property should have a setter */
   set?: boolean;
+
+  /** Doc comment */
+  doc?: Children;
 }
 
 // a C# interface property
@@ -71,6 +75,7 @@ export function InterfaceProperty(props: InterfacePropertyProps) {
   return (
     <MemberDeclaration symbol={propertySymbol}>
       <Scope value={propertyScope}>
+        <DocWhen doc={props.doc} />
         {modifiers}
         {props.type} {name}{" "}
         <Block newline inline>