feat: add website documentation early mvp (#8183)

Co-authored-by: iCrawl <buechler.noel@outlook.com>

packages/website/src/DocModel/DocClass.ts

@@ -0,0 +1,52 @@
+import {
+	type ApiClass,
+	type ApiModel,
+	ApiItemKind,
+	type ApiMethod,
+	type ApiPropertyItem,
+} from '@microsoft/api-extractor-model';
+import { DocItem } from './DocItem';
+import { DocMethod } from './DocMethod';
+import { DocProperty } from './DocProperty';
+import { type TokenDocumentation, genToken } from '~/util/parse.server';
+
+export class DocClass extends DocItem<ApiClass> {
+	public readonly extendsTokens: TokenDocumentation[] | null;
+	public readonly implementsTokens: TokenDocumentation[][];
+	public readonly methods: DocMethod[] = [];
+	public readonly properties: DocProperty[] = [];
+
+	public constructor(model: ApiModel, item: ApiClass) {
+		super(model, item);
+		const extendsExcerpt = item.extendsType?.excerpt;
+		this.extendsTokens = extendsExcerpt
+			? extendsExcerpt.spannedTokens.map((token) => genToken(this.model, token))
+			: null;
+		this.implementsTokens = item.implementsTypes.map((excerpt) =>
+			excerpt.excerpt.spannedTokens.map((token) => genToken(this.model, token)),
+		);
+
+		for (const member of item.members) {
+			switch (member.kind) {
+				case ApiItemKind.Method:
+					this.methods.push(new DocMethod(this.model, member as ApiMethod));
+					break;
+				case ApiItemKind.Property:
+					this.properties.push(new DocProperty(this.model, member as ApiPropertyItem));
+					break;
+				default:
+					break;
+			}
+		}
+	}
+
+	public override toJSON() {
+		return {
+			...super.toJSON(),
+			extendsTokens: this.extendsTokens,
+			implementsTokens: this.implementsTokens,
+			methods: this.methods.map((method) => method.toJSON()),
+			properties: this.properties.map((prop) => prop.toJSON()),
+		};
+	}
+}

packages/website/src/DocModel/DocEnum.ts

@@ -0,0 +1,25 @@
+import type { ApiEnum, ApiModel } from '@microsoft/api-extractor-model';
+import { DocItem } from './DocItem';
+
+export interface EnumMemberData {
+	name: string;
+}
+
+export class DocEnum extends DocItem<ApiEnum> {
+	public readonly members: EnumMemberData[] = [];
+
+	public constructor(model: ApiModel, item: ApiEnum) {
+		super(model, item);
+
+		this.members = item.members.map((member) => ({
+			name: member.name,
+		}));
+	}
+
+	public override toJSON() {
+		return {
+			...super.toJSON(),
+			members: this.members,
+		};
+	}
+}

packages/website/src/DocModel/DocFunction.ts

@@ -0,0 +1,25 @@
+import type { ApiFunction, ApiModel } from '@microsoft/api-extractor-model';
+import { DocItem } from './DocItem';
+import { type ParameterDocumentation, type TokenDocumentation, genParameter, genToken } from '~/util/parse.server';
+
+export class DocFunction extends DocItem<ApiFunction> {
+	public readonly parameters: ParameterDocumentation[];
+	public readonly returnTypeTokens: TokenDocumentation[];
+	public readonly overloadIndex: number;
+
+	public constructor(model: ApiModel, item: ApiFunction) {
+		super(model, item);
+		this.parameters = item.parameters.map((param) => genParameter(this.model, param));
+		this.returnTypeTokens = item.returnTypeExcerpt.spannedTokens.map((token) => genToken(this.model, token));
+		this.overloadIndex = item.overloadIndex;
+	}
+
+	public override toJSON() {
+		return {
+			...super.toJSON(),
+			parameters: this.parameters,
+			returnTypeTokens: this.returnTypeTokens,
+			overloadIndex: this.overloadIndex,
+		};
+	}
+}

packages/website/src/DocModel/DocInterface.ts

@@ -0,0 +1,41 @@
+import { DocItem } from './DocItem';
+import { DocMethodSignature } from './DocMethodSignature';
+import { DocProperty } from './DocProperty';
+import { ApiInterface, ApiItemKind, ApiMethodSignature, ApiModel, ApiPropertySignature } from '~/api-extractor.server';
+import { type TokenDocumentation, genToken } from '~/util/parse.server';
+
+export class DocInterface extends DocItem<ApiInterface> {
+	public readonly extendsTokens: TokenDocumentation[][] | null;
+	public readonly methods: DocMethodSignature[] = [];
+	public readonly properties: DocProperty[] = [];
+
+	public constructor(model: ApiModel, item: ApiInterface) {
+		super(model, item);
+
+		this.extendsTokens = item.extendsTypes.map((excerpt) =>
+			excerpt.excerpt.spannedTokens.map((token) => genToken(this.model, token)),
+		);
+
+		for (const member of item.members) {
+			switch (member.kind) {
+				case ApiItemKind.MethodSignature:
+					this.methods.push(new DocMethodSignature(this.model, member as ApiMethodSignature));
+					break;
+				case ApiItemKind.PropertySignature:
+					this.properties.push(new DocProperty(this.model, member as ApiPropertySignature));
+					break;
+				default:
+					break;
+			}
+		}
+	}
+
+	public override toJSON() {
+		return {
+			...super.toJSON(),
+			extendsTokens: this.extendsTokens,
+			methods: this.methods.map((method) => method.toJSON()),
+			properties: this.properties.map((prop) => prop.toJSON()),
+		};
+	}
+}

packages/website/src/DocModel/DocItem.ts

@@ -0,0 +1,36 @@
+import type { ApiModel, ApiDeclaredItem } from '@microsoft/api-extractor-model';
+import type { ReferenceData } from '~/model.server';
+import { resolveName, genReference, resolveDocComment, TokenDocumentation, genToken } from '~/util/parse.server';
+
+export class DocItem<T extends ApiDeclaredItem = ApiDeclaredItem> {
+	public readonly item: T;
+	public readonly name: string;
+	public readonly referenceData: ReferenceData;
+	public readonly summary: string | null;
+	public readonly model: ApiModel;
+	public readonly excerpt: string;
+	public readonly excerptTokens: TokenDocumentation[] = [];
+	public readonly kind: string;
+
+	public constructor(model: ApiModel, item: T) {
+		this.item = item;
+		this.kind = item.kind;
+		this.model = model;
+		this.name = resolveName(item);
+		this.referenceData = genReference(item);
+		this.summary = resolveDocComment(item);
+		this.excerpt = item.excerpt.text;
+		this.excerptTokens = item.excerpt.spannedTokens.map((token) => genToken(model, token));
+	}
+
+	public toJSON() {
+		return {
+			name: this.name,
+			referenceData: this.referenceData,
+			summary: this.summary,
+			excerpt: this.excerpt,
+			excerptTokens: this.excerptTokens,
+			kind: this.kind,
+		};
+	}
+}

packages/website/src/DocModel/DocMethod.ts

@@ -0,0 +1,35 @@
+import type { ApiMethod, ApiModel } from '@microsoft/api-extractor-model';
+import { DocItem } from './DocItem';
+import { Visibility } from './Visibility';
+import { type ParameterDocumentation, type TokenDocumentation, genParameter, genToken } from '~/util/parse.server';
+
+export class DocMethod extends DocItem<ApiMethod> {
+	public readonly parameters: ParameterDocumentation[];
+	public readonly static: boolean;
+	public readonly optional: boolean;
+	public readonly visibility: Visibility;
+	public readonly returnTypeTokens: TokenDocumentation[];
+	public readonly overloadIndex: number;
+
+	public constructor(model: ApiModel, item: ApiMethod) {
+		super(model, item);
+		this.parameters = item.parameters.map((param) => genParameter(this.model, param));
+		this.static = item.isStatic;
+		this.optional = item.isOptional;
+		this.visibility = item.isProtected ? Visibility.Protected : Visibility.Public;
+		this.returnTypeTokens = item.returnTypeExcerpt.spannedTokens.map((token) => genToken(this.model, token));
+		this.overloadIndex = item.overloadIndex;
+	}
+
+	public override toJSON() {
+		return {
+			...super.toJSON(),
+			static: this.static,
+			optional: this.optional,
+			visibility: this.visibility,
+			parameters: this.parameters,
+			returnTypeTokens: this.returnTypeTokens,
+			overloadIndex: this.overloadIndex,
+		};
+	}
+}

packages/website/src/DocModel/DocMethodSignature.ts

@@ -0,0 +1,28 @@
+import type { ApiMethodSignature, ApiModel } from '@microsoft/api-extractor-model';
+import { DocItem } from './DocItem';
+import { type ParameterDocumentation, type TokenDocumentation, genParameter, genToken } from '~/util/parse.server';
+
+export class DocMethodSignature extends DocItem<ApiMethodSignature> {
+	public readonly parameters: ParameterDocumentation[];
+	public readonly optional: boolean;
+	public readonly returnTypeTokens: TokenDocumentation[];
+	public readonly overloadIndex: number;
+
+	public constructor(model: ApiModel, item: ApiMethodSignature) {
+		super(model, item);
+		this.parameters = item.parameters.map((param) => genParameter(this.model, param));
+		this.optional = item.isOptional;
+		this.returnTypeTokens = item.returnTypeExcerpt.spannedTokens.map((token) => genToken(this.model, token));
+		this.overloadIndex = item.overloadIndex;
+	}
+
+	public override toJSON() {
+		return {
+			...super.toJSON(),
+			optional: this.optional,
+			parameters: this.parameters,
+			returnTypeTokens: this.returnTypeTokens,
+			overloadIndex: this.overloadIndex,
+		};
+	}
+}

packages/website/src/DocModel/DocProperty.ts

@@ -0,0 +1,25 @@
+import type { ApiPropertyItem, ApiModel, ApiPropertySignature } from '@microsoft/api-extractor-model';
+import { DocItem } from './DocItem';
+import { type TokenDocumentation, genToken } from '~/util/parse.server';
+
+export class DocProperty extends DocItem<ApiPropertyItem> {
+	public readonly propertyTypeTokens: TokenDocumentation[];
+	public readonly readonly: boolean;
+	public readonly optional: boolean;
+
+	public constructor(model: ApiModel, item: ApiPropertyItem | ApiPropertySignature) {
+		super(model, item);
+		this.propertyTypeTokens = item.propertyTypeExcerpt.spannedTokens.map((token) => genToken(this.model, token));
+		this.readonly = item.isReadonly;
+		this.optional = item.isOptional;
+	}
+
+	public override toJSON() {
+		return {
+			...super.toJSON(),
+			propertyTypeTokens: this.propertyTypeTokens,
+			readonly: this.readonly,
+			optional: this.optional,
+		};
+	}
+}

packages/website/src/DocModel/DocTypeAlias.ts

@@ -0,0 +1,19 @@
+import type { ApiModel, ApiTypeAlias } from '@microsoft/api-extractor-model';
+import { DocItem } from './DocItem';
+import { type TokenDocumentation, genToken } from '~/util/parse.server';
+
+export class DocTypeAlias extends DocItem<ApiTypeAlias> {
+	public readonly typeTokens: TokenDocumentation[];
+
+	public constructor(model: ApiModel, item: ApiTypeAlias) {
+		super(model, item);
+		this.typeTokens = item.typeExcerpt.spannedTokens.map((token) => genToken(model, token));
+	}
+
+	public override toJSON() {
+		return {
+			...super.toJSON(),
+			typeTokens: this.typeTokens,
+		};
+	}
+}

packages/website/src/DocModel/DocVariable.ts

@@ -0,0 +1,22 @@
+import type { ApiModel, ApiVariable } from '@microsoft/api-extractor-model';
+import { DocItem } from './DocItem';
+import { genToken, TokenDocumentation } from '~/util/parse.server';
+
+export class DocVariable extends DocItem<ApiVariable> {
+	public readonly typeTokens: TokenDocumentation[] = [];
+	public readonly readonly: boolean;
+
+	public constructor(model: ApiModel, item: ApiVariable) {
+		super(model, item);
+		this.typeTokens = item.variableTypeExcerpt.spannedTokens.map((token) => genToken(model, token));
+		this.readonly = item.isReadonly;
+	}
+
+	public override toJSON() {
+		return {
+			...super.toJSON(),
+			typeTokens: this.typeTokens,
+			readonly: this.readonly,
+		};
+	}
+}

packages/website/src/DocModel/Visibility.ts

@@ -0,0 +1,4 @@
+export enum Visibility {
+	Public,
+	Protected,
+}