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

package/src/components/ClassMethod.tsx

@@ -11,16 +11,33 @@ import {
   computeModifiersPrefix,
   getAccessModifier,
   getAsyncModifier,
-  getMethodModifier,
-  MethodModifiers,
+  makeModifiers,
 } from "../modifiers.js";
 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 ClassMethodModifiers {
+  readonly abstract?: boolean;
+  readonly sealed?: boolean;
+  readonly static?: boolean;
+  readonly virtual?: boolean;
+}
+
+const getMethodModifier = makeModifiers<ClassMethodModifiers>([
+  "abstract",
+  "sealed",
+  "static",
+  "virtual",
+]);
 
 // properties for creating a method
-export interface ClassMethodProps extends AccessModifiers, MethodModifiers {
+export interface ClassMethodProps
+  extends AccessModifiers,
+    ClassMethodModifiers {
   name: string;
   refkey?: Refkey;
   children?: Children;
@@ -31,6 +48,9 @@ export interface ClassMethodProps extends AccessModifiers, MethodModifiers {
    * If true, the method will be declared as an async method.
    */
   async?: boolean;
+
+  /** Doc comment */
+  doc?: Children;
 }
 
 // a C# class method
@@ -64,6 +84,7 @@ export function ClassMethod(props: ClassMethodProps) {
   return (
     <MemberDeclaration symbol={methodSymbol}>
       <Scope value={methodScope}>
+        <DocWhen doc={props.doc} />
         {modifiers}
         {returns} {name}({params})
         {props.abstract ? ";" : <Block newline>{props.children}</Block>}

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/index.ts

@@ -1,7 +1,9 @@
 export * from "./ClassDeclaration.jsx";
-export { ClassMethod, type ClassMethodProps } from "./ClassMethod.jsx";
+export * from "./ClassMethod.jsx";
 export * from "./Declaration.js";
 export * from "./EnumDeclaration.jsx";
+export * from "./interface/declaration.js";
+export * from "./interface/method.js";
 export * from "./Name.js";
 export * from "./Namespace.js";
 export * from "./Parameters.js";

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

@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest";
+import { TestNamespace } from "../../../test/utils.jsx";
+import { InterfaceDeclaration } from "./declaration.jsx";
+
+it("declares class with no members", () => {
+  expect(
+    <TestNamespace>
+      <InterfaceDeclaration name="TestInterface" />
+    </TestNamespace>,
+  ).toRenderTo(`
+      interface TestInterface;
+  `);
+});
+
+describe("modifiers", () => {
+  it.each(["public", "private", "internal"])("%s", (mod) => {
+    expect(
+      <TestNamespace>
+        <InterfaceDeclaration {...{ [mod]: true }} name="TestInterface" />
+      </TestNamespace>,
+    ).toRenderTo(`
+        ${mod} interface TestInterface;
+    `);
+  });
+
+  it.each(["partial"])("%s", (mod) => {
+    expect(
+      <TestNamespace>
+        <InterfaceDeclaration {...{ [mod]: true }} name="TestInterface" />
+      </TestNamespace>,
+    ).toRenderTo(`
+        ${mod} interface TestInterface;
+    `);
+  });
+
+  it("combines modifiers", () => {
+    expect(
+      <TestNamespace>
+        <InterfaceDeclaration public partial name="TestInterface" />
+      </TestNamespace>,
+    ).toRenderTo(`
+        public partial interface TestInterface;
+    `);
+  });
+});
+
+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

@@ -0,0 +1,109 @@
+import * as core from "@alloy-js/core";
+import {
+  AccessModifiers,
+  computeModifiersPrefix,
+  getAccessModifier,
+  makeModifiers,
+} from "../../modifiers.js";
+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 {
+  readonly partial?: boolean;
+}
+
+const getInterfaceModifiers = makeModifiers<InterfaceModifiers>(["partial"]);
+
+// properties for creating a class
+export interface InterfaceDeclarationProps
+  extends Omit<core.DeclarationProps, "nameKind">,
+    AccessModifiers,
+    InterfaceModifiers {
+  name: string;
+
+  /** Doc comment */
+  doc?: core.Children;
+  refkey?: core.Refkey;
+  typeParameters?: Record<string, core.Refkey>;
+}
+
+/**
+ * CSharp interface declaration.
+ * @example
+ * ```tsx
+ * <InterfaceDeclaration public name="IMyInterface">
+ *   <InterfaceMember public name="MyProperty" type="int" />
+ *   <InterfaceMethod public name="MyMethod" returnType="void">
+ *     <Parameter name="value" type="int" />
+ *   </InterfaceMethod>
+ * </InterfaceDeclaration>
+ * ```
+ * This will produce:
+ * ```csharp
+ * public interface MyIface
+ * {
+ *   public int MyProperty { get; set; }
+ *   public void MyMethod(int value);
+ * }
+ * ```
+ */
+export function InterfaceDeclaration(props: InterfaceDeclarationProps) {
+  const name = useCSharpNamePolicy().getName(props.name!, "interface");
+
+  const thisInterfaceSymbol = new CSharpOutputSymbol(name, {
+    refkeys: props.refkey,
+  });
+
+  // this creates a new scope for the interface definition.
+  // members will automatically "inherit" this scope so
+  // that refkeys to them will produce the fully-qualified
+  // name e.g. Foo.Bar.
+  const thisInterfaceScope = new CSharpMemberScope("interface-decl", {
+    owner: thisInterfaceSymbol,
+  });
+
+  let typeParams: core.Children;
+  if (props.typeParameters) {
+    const typeParamNames = new Array<string>();
+    for (const entry of Object.entries(props.typeParameters)) {
+      typeParamNames.push(
+        useCSharpNamePolicy().getName(entry[0], "type-parameter"),
+      );
+      // create a symbol for each type param so its
+      // refkey resolves to the type param's name
+      new CSharpOutputSymbol(entry[0], {
+        scope: thisInterfaceScope,
+        refkeys: entry[1],
+      });
+    }
+    typeParams = (
+      <group>
+        {"<"}
+        <core.For each={typeParamNames} comma line>
+          {(name) => name}
+        </core.For>
+        {">"}
+      </group>
+    );
+  }
+
+  const modifiers = computeModifiersPrefix([
+    getAccessModifier(props),
+    getInterfaceModifiers(props),
+  ]);
+  return (
+    <core.Declaration symbol={thisInterfaceSymbol}>
+      <DocWhen doc={props.doc} />
+      {modifiers}interface <Name />
+      {typeParams}
+      {props.children ?
+        <core.Block newline>
+          <core.Scope value={thisInterfaceScope}>{props.children}</core.Scope>
+        </core.Block>
+      : ";"}
+    </core.Declaration>
+  );
+}