Feature: Class plugin (#11)

Author: Martynas Žilinskas

packages/ts-docs-gen/examples/simple/docs/api/index.md

@@ -1,22 +1,5 @@
-[ModuleDeclaration-0]: index\foonamespace.md#foonamespace
+[ClassDeclaration-0]: index/hello.md#hello
 # index
 
-## MyFunction()
-
-```typescript
-function MyFunction<T extends { myProperty: string; myPropertyTwo?: number | undefined; } = { myProperty: string; }>(): T
-```
-
-### Type parameters
-
-| Name | Constraint type                                                | Default type              |
-| ---- | -------------------------------------------------------------- | ------------------------- |
-| T    | \{ myProperty: string; myPropertyTwo?: number \| undefined; \} | \{ myProperty: string; \} |
-
-### Return type
-
-T
-
-
-## [FooNamespace][ModuleDeclaration-0]
+## [Hello][ClassDeclaration-0]
 

packages/ts-docs-gen/examples/simple/docs/api/index/hello.md

@@ -0,0 +1,71 @@
+# Hello
+
+```typescript
+class Hello
+```
+## Constructor
+
+### constructor(arg)
+
+This is a constructor
+
+```typescript
+constructor(arg: string)
+```
+#### Parameters
+
+| Name | Type   | Description            |
+| ---- | ------ | ---------------------- |
+| arg  | string | This is an argument ;) |
+
+
+## Methods
+
+### GetFoo(arg)
+
+```typescript
+public GetFoo(arg: number): string
+```
+#### Parameters
+
+| Name | Type   |
+| ---- | ------ |
+| arg  | number |
+
+
+### GetFoo(arg)
+
+```typescript
+public GetFoo(arg: string): string
+```
+#### Parameters
+
+| Name | Type   |
+| ---- | ------ |
+| arg  | string |
+
+
+### GetFoo(arg)
+
+```typescript
+public GetFoo(arg: string | number): string
+```
+#### Parameters
+
+| Name | Type             |
+| ---- | ---------------- |
+| arg  | string \| number |
+
+
+## Properties
+
+### Foo
+
+```typescript
+public Foo: string;
+```
+
+### Type
+
+string
+

packages/ts-docs-gen/examples/simple/index.ts

@@ -79,11 +79,11 @@
 //     anotherProperty: number;
 // }
 
-export function MyFunction<T extends { myProperty: string, myPropertyTwo?: number } = { myProperty: string }>(): T {
-    return {
-        myProperty: "sampleString"
-    } as T;
-}
+// export function MyFunction<T extends { myProperty: string, myPropertyTwo?: number } = { myProperty: string }>(): T {
+//     return {
+//         myProperty: "sampleString"
+//     } as T;
+// }
 
 // export interface MyInterface {
 //     <TValue>(param1: TValue, param2: TValue): boolean;
@@ -203,10 +203,26 @@ export function MyFunction<T extends { myProperty: string, myPropertyTwo?: numbe
 //  */
 // export type Hello = Uogos;
 
-export namespace FooNamespace {
-    export namespace BooNamespace {
-        export namespace BooNamespace2 {
-            export const Hello = "World!";
-        }
+// export namespace FooNamespace {
+//     export namespace BooNamespace {
+//         export namespace BooNamespace2 {
+//             export const Hello = "World!";
+//         }
+//     }
+// }
+
+export class Hello {
+    /**
+     * This is a constructor
+     * @param arg This is an argument ;)
+     */
+    constructor(arg: string) { }
+
+    GetFoo(arg: number): string
+    GetFoo(arg: string): string
+    GetFoo(arg: string | number): string {
+        throw new Error("Method not implemented.");
     }
+
+    public Foo: string;
 }

packages/ts-docs-gen/src/contracts/plugin.ts

@@ -29,9 +29,7 @@ export interface PluginOptions<TKind = Contracts.ApiItemDto> {
     IsPluginResultExists: IsPluginResultExistsHandler;
 }
 
-export interface PluginResult<TKind = Contracts.ApiItemDto> {
-    Reference: ApiItemReference;
-    ApiItem: TKind;
+export interface PluginResultData {
     /**
      * All headings used in `Result` with ApiItemIds.
      */
@@ -47,6 +45,11 @@ export interface PluginResult<TKind = Contracts.ApiItemDto> {
     Members?: PluginMember[];
 }
 
+export interface PluginResult<TKind = Contracts.ApiItemDto> extends PluginResultData {
+    Reference: ApiItemReference;
+    ApiItem: TKind;
+}
+
 export interface Plugin<TKind = Contracts.ApiItemDto> {
     SupportedApiItemKinds(): SupportedApiItemKindType[];
     CheckApiItem(item: TKind): boolean;

packages/ts-docs-gen/src/default-plugins.ts

@@ -4,12 +4,20 @@ import { ApiEnumPlugin } from "./plugins/api-enum-plugin";
 import { ApiFunctionPlugin } from "./plugins/api-function-plugin";
 import { ApiTypePlugin } from "./plugins/api-type-plugin";
 import { ApiNamespacePlugin } from "./plugins/api-namespace-plugin";
+import { ApiClassPlugin } from "./plugins/api-class-plugin";
+import { ApiClassConstructorPlugin } from "./plugins/api-class-constructor-plugin";
+import { ApiClassMethodPlugin } from "./plugins/api-class-method-plugin";
+import { ApiClassPropertyPlugin } from "./plugins/api-class-property-plugin";
 
 export const DefaultPlugins = [
     new ApiSourceFilePlugin(),
     new ApiVariablePlugin(),
     new ApiEnumPlugin(),
     new ApiFunctionPlugin(),
     new ApiTypePlugin(),
-    new ApiNamespacePlugin()
+    new ApiNamespacePlugin(),
+    new ApiClassPlugin(),
+    new ApiClassConstructorPlugin(),
+    new ApiClassMethodPlugin(),
+    new ApiClassPropertyPlugin()
 ];

packages/ts-docs-gen/src/generator-helpers.ts

@@ -4,7 +4,7 @@ import { MarkdownGenerator, MarkdownBuilder, Contracts as MarkdownContracts } fr
 import * as path from "path";
 
 import { ApiItemReference } from "./contracts/api-item-reference";
-import { ApiItemKindsAdditional } from "./contracts/plugin";
+import { ApiItemKindsAdditional, PluginResultData } from "./contracts/plugin";
 import { Logger } from "./utils/logger";
 
 export namespace GeneratorHelpers {
@@ -306,6 +306,43 @@ export namespace GeneratorHelpers {
         return `${apiItem.Name}${$extends}${defaultType}`;
     }
 
+    export function ClassToString(
+        apiItem: Contracts.ApiClassDto,
+        typeParameters?: Contracts.ApiTypeParameterDto[],
+        alias?: string
+    ): string {
+        const name = alias || apiItem.Name;
+        // Abstract
+        const abstract = apiItem.IsAbstract ? "abstract " : "";
+
+        // TypeParameters
+        let typeParametersString: string;
+        if (typeParameters != null && typeParameters.length > 0) {
+            const params: string[] = typeParameters.map(TypeParameterToString);
+            typeParametersString = `<${params.join(", ")}>`;
+        } else {
+            typeParametersString = "";
+        }
+
+        // Extends
+        let extendsString: string;
+        if (apiItem.Extends != null) {
+            extendsString = ` extends ${apiItem.Extends.Text}`;
+        } else {
+            extendsString = "";
+        }
+
+        // Implements
+        let implementsString: string;
+        if (apiItem.Implements != null && apiItem.Implements.length > 0) {
+            implementsString = ` implements ${apiItem.Implements.map(x => x.Text).join(", ")}`;
+        } else {
+            implementsString = "";
+        }
+
+        return `${abstract}class ${name}${typeParametersString}${extendsString}${implementsString}`;
+    }
+
     export function ApiFunctionToSimpleString(
         alias: string,
         apiItem: Contracts.ApiFunctionDto,
@@ -319,6 +356,66 @@ export namespace GeneratorHelpers {
         return `${name}(${parametersString})`;
     }
 
+    export function ApiClassMethodToString(
+        apiItem: Contracts.ApiClassMethodDto,
+        parameters: Contracts.ApiParameterDto[],
+        alias?: string
+    ): string {
+        const name = alias || apiItem.Name;
+
+        const optional = apiItem.IsOptional ? "?" : "";
+        const abstract = apiItem.IsAbstract ? " abstract" : "";
+        const async = apiItem.IsAsync ? " async" : "";
+        const $static = apiItem.IsStatic ? " static" : "";
+        const functionHeader = CallableParametersToString(`${name}${optional}`, parameters, apiItem.ReturnType);
+
+        return `${apiItem.AccessModifier}${$static}${abstract}${async} ${functionHeader}`.trim();
+    }
+
+    export function ApiClassPropertyToString(apiItem: Contracts.ApiClassPropertyDto, alias?: string): string {
+        const name = alias || apiItem.Name;
+
+        const optional = apiItem.IsOptional ? "?" : "";
+        const abstract = apiItem.IsAbstract ? " abstract" : "";
+        const $static = apiItem.IsStatic ? " static" : "";
+
+        return `${apiItem.AccessModifier}${$static}${abstract} ${name}${optional}: ${apiItem.Type.Text};`;
+    }
+
+    export function CallableParametersToSimpleString(text: string, parameters: Contracts.ApiParameterDto[]): string {
+        const parametersString = parameters
+            .map(x => x.Name)
+            .join(", ");
+
+        return `${text}(${parametersString})`;
+    }
+
+    export function CallableParametersToString(
+        text: string,
+        parameters: Contracts.ApiParameterDto[],
+        returnType?: Contracts.TypeDto
+    ): string {
+        // Parameters
+        let parametersString: string;
+        if (parameters != null && parameters.length > 0) {
+            parametersString = parameters
+                .map(x => `${x.Name}: ${x.Type.Text}`)
+                .join(", ");
+        } else {
+            parametersString = "";
+        }
+
+        // ReturnType
+        let returnTypeString: string;
+        if (returnType != null) {
+            returnTypeString = `: ${returnType.Text}`;
+        } else {
+            returnTypeString = "";
+        }
+
+        return `${text}(${parametersString})${returnTypeString}`;
+    }
+
     export function GetApiItemsFromReference<T extends Contracts.ApiItemDto>(
         items: Contracts.ApiItemReference[],
         extractedData: ExtractDto
@@ -344,4 +441,21 @@ export namespace GeneratorHelpers {
     export function StandardisePath(pathString: string): string {
         return pathString.split(path.sep).join("/");
     }
+
+    export function MergePluginResultData<T extends PluginResultData>(a: T, b: Partial<PluginResultData>): T {
+        a.Headings = a.Headings.concat(b.Headings || []);
+        a.Members = (a.Members || []).concat(b.Members || []);
+        a.Result = a.Result.concat(b.Result || []);
+        a.UsedReferences = a.UsedReferences.concat(b.UsedReferences || []);
+
+        return a;
+    }
+
+    export function GetDefaultPluginResultData(): PluginResultData {
+        return {
+            Headings: [],
+            Result: [],
+            UsedReferences: []
+        };
+    }
 }