feat(api-markdown-documenter): Add limited support for inherited type member docs

tools/api-markdown-documenter/src/api-item-transforms/helpers/TableHelpers.ts

@@ -17,7 +17,7 @@ import {
 } from "@microsoft/api-extractor-model";
 import type { DocSection } from "@microsoft/tsdoc";
 import { toHtml } from "hast-util-to-html";
-import type { Html, PhrasingContent, Table, TableCell } from "mdast";
+import type { BlockContent, Html, PhrasingContent, Table, TableCell } from "mdast";
 import { toHast } from "mdast-util-to-hast";
 
 import type { Section } from "../../mdast/index.js";
@@ -564,7 +564,7 @@ export function createPackagesTable(
  * @param apiItem - The API item whose comment will be rendered in the cell.
  * @param config - See {@link ApiItemTransformationConfiguration}.
  */
-function createDescriptionCell(
+export function createDescriptionCell(
 	apiItem: ApiItem,
 	config: ApiItemTransformationConfiguration,
 ): TableCell | undefined {
@@ -588,7 +588,7 @@ function createDescriptionCell(
  * will point.
  * @param config - See {@link ApiItemTransformationConfiguration}.
  */
-function createNameCell(
+export function createNameCell(
 	apiItem: ApiItem,
 	config: ApiItemTransformationConfiguration,
 ): TableCell {
@@ -605,7 +605,7 @@ function createNameCell(
  * @param apiItem - The API item whose modifiers will be displayed in the cell.
  * @param modifiersToOmit - List of modifiers to omit from the generated cell, even if they apply to the item.
  */
-function createModifiersCell(
+export function createModifiersCell(
 	apiItem: ApiItem,
 	modifiersToOmit?: ApiModifier[],
 ): TableCell | undefined {
@@ -635,7 +635,7 @@ function createModifiersCell(
  * @param apiItem - The alert values to display.
  * @param config - See {@link ApiItemTransformationConfiguration}.
  */
-function createAlertsCell(alerts: string[]): TableCell | undefined {
+export function createAlertsCell(alerts: string[]): TableCell | undefined {
 	const alertNodes: PhrasingContent[] = alerts.map((alert) => ({
 		type: "inlineCode",
 		value: alert,
@@ -716,7 +716,7 @@ function createTypeParameterSummaryCell(
  * @param typeExcerpt - An excerpt describing the type to be displayed in the cell.
  * @param config - See {@link ApiItemTransformationConfiguration}.
  */
-function createTypeExcerptCell(
+export function createTypeExcerptCell(
 	typeExcerpt: Excerpt,
 	config: ApiItemTransformationConfiguration,
 ): TableCell | undefined {
@@ -765,29 +765,41 @@ function getTableHeadingTitleForApiKind(itemKind: ApiItemKind): string {
  * Notably, this optimizes away the generation of paragraph nodes around inner contents when there is only a
  * single paragraph.
  */
-function createTableCellFromTsdocSection(
+export function createTableCellFromTsdocSection(
 	tsdocSection: DocSection,
 	contextApiItem: ApiItem,
 	config: ApiItemTransformationConfiguration,
 ): TableCell | undefined {
 	const transformed = transformTsdoc(tsdocSection, contextApiItem, config);
+	return createTableCellFromBlockContent(transformed);
+}
 
-	if (transformed.length === 0) {
+/**
+ * Transforms the contents of a TSDoc section node, and fine-tunes the output for use in a table cell.
+ *
+ * @remarks
+ * Notably, this optimizes away the generation of paragraph nodes around inner contents when there is only a
+ * single paragraph.
+ */
+function createTableCellFromBlockContent(
+	blockContent: readonly BlockContent[],
+): TableCell | undefined {
+	if (blockContent.length === 0) {
 		return undefined;
 	}
 
 	// If the transformed contents consist of a single paragraph (common case), inline that paragraph's contents
 	// directly in the cell.
-	if (transformed.length === 1 && transformed[0].type === "paragraph") {
+	if (blockContent.length === 1 && blockContent[0].type === "paragraph") {
 		return {
 			type: "tableCell",
-			children: transformed[0].children,
+			children: blockContent[0].children,
 		};
 	}
 
 	// `mdast` does not allow block content in table cells, but we want to be able to include things like fenced code blocks, etc. in our table cells.
 	// To accommodate this, we convert the contents to HTML and put that inside the table cell.
-	const htmlTrees = transformed.map((node) => toHast(node));
+	const htmlTrees = blockContent.map((node) => toHast(node));
 	const htmlNodes: Html[] = htmlTrees.map((node) => ({
 		type: "html",
 		value: toHtml(node),

tools/api-markdown-documenter/src/api-item-transforms/helpers/index.ts

@@ -11,5 +11,6 @@
 
 export * from "./Helpers.js";
 export * from "./TableHelpers.js";
+export { createTableFromItems } from "./TableCreation.js";
 
 /* eslint-enable no-restricted-syntax */

tools/api-markdown-documenter/src/api-item-transforms/utilities/InheritanceUtilities.ts

@@ -0,0 +1,204 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import {
+	type ApiClass,
+	type ApiInterface,
+	type ApiItem,
+	ApiItemKind,
+	type HeritageType,
+} from "@microsoft/api-extractor-model";
+
+import {
+	getApiItemKind,
+	type ApiTypeLike,
+	isTypeLike,
+	isStatic,
+} from "../../utilities/index.js";
+import type { ApiItemTransformationConfiguration } from "../configuration/index.js";
+
+import { filterItems } from "./ApiItemTransformUtilities.js";
+
+/**
+ * API-Extractor does not directly provide a way to get inherited members of an API item.
+ * These utilities work around that limitation to provide a best-effort approximation of inherited members.
+ *
+ * If, in the future, API-Extractor provides a better way to get inherited members, these utilities should be updated or removed as appropriate.
+ */
+
+/**
+ * {@link TypeMember} base interface.
+ */
+export interface TypeMemberBase<TApiItem extends ApiItem = ApiItem> {
+	/**
+	 * The kind of type member.
+	 * "own" if the member is directly declared on the API item.
+	 * "inherited" if the member is inherited from a base type.
+	 */
+	readonly kind: "own" | "inherited";
+
+	/**
+	 * The API item that is the member.
+	 */
+	readonly item: TApiItem;
+}
+
+/**
+ * Represents a type member that is directly declared on the API item.
+ */
+export interface OwnTypeMember<TApiItem extends ApiItem = ApiItem>
+	extends TypeMemberBase<TApiItem> {
+	readonly kind: "own";
+
+	/**
+	 * The member on some base type that this member overrides, if any.
+	 * @remarks For example, if this member is a method that overrides a method on a base class, this would be that base method.
+	 */
+	readonly baseDefinition: ApiItem | undefined;
+}
+
+/**
+ * Represents a type member that is inherited from a base type.
+ */
+export interface InheritedTypeMember<TApiItem extends ApiItem = ApiItem>
+	extends TypeMemberBase<TApiItem> {
+	readonly kind: "inherited";
+
+	/**
+	 * The API item from which this member is inherited.
+	 * @remarks For example, if this member is a method inherited from a base class, this would be that base class.
+	 */
+	readonly baseDefinition: ApiItem;
+}
+
+/**
+ * A type member, which may be either directly declared on the API item or inherited from a base type.
+ */
+export type TypeMember<TApiItem extends ApiItem = ApiItem> =
+	| OwnTypeMember<TApiItem>
+	| InheritedTypeMember<TApiItem>;
+
+/**
+ * Gets the members of the specified API item, including inherited members where applicable.
+ * @param apiItem - The API item being queried.
+ * @param config - See {@link ApiItemTransformationConfiguration}.
+ */
+export function getTypeMembers<TApiItem extends ApiTypeLike>(
+	apiItem: TApiItem,
+	config: ApiItemTransformationConfiguration,
+): TypeMember[] {
+	// Get inherited members
+	const inheritedMembers: InheritedTypeMember[] = [];
+	if (apiItem.kind === ApiItemKind.Class) {
+		const apiClass = apiItem as ApiClass;
+
+		// Inherit members from `extends` clause
+		if (apiClass.extendsType !== undefined) {
+			inheritedMembers.push(...getInheritedMembers(apiClass, apiClass.extendsType, config));
+		}
+
+		// Inherit members from `implements` clauses
+		for (const implementsType of apiClass.implementsTypes) {
+			inheritedMembers.push(...getInheritedMembers(apiClass, implementsType, config));
+		}
+	} else if (apiItem.kind === ApiItemKind.Interface) {
+		const apiInterface = apiItem as ApiInterface;
+
+		// Inherit members from `extends` clauses
+		for (const extendsType of apiInterface.extendsTypes) {
+			inheritedMembers.push(...getInheritedMembers(apiInterface, extendsType, config));
+		}
+	} else {
+		// TODO: type-alias
+	}
+
+	const ownMemberItems = filterItems(apiItem.members, config);
+
+	const ownMembers: OwnTypeMember[] = [];
+	for (const ownMemberItem of ownMemberItems) {
+		const override = inheritedMembers.find(
+			// TODO: verify this is a sufficient check for API match
+			(inherited) => inherited.item.containerKey === ownMemberItem.containerKey,
+		);
+
+		// If this member overrides a base member, remove that base member from the inherited members list.
+		// We only want to display our override.
+		if (override) {
+			inheritedMembers.splice(inheritedMembers.indexOf(override), 1);
+		}
+
+		ownMembers.push({
+			kind: "own",
+			item: ownMemberItem,
+			baseDefinition: override?.item,
+		});
+	}
+
+	// TODO: document ordering
+	return [...inheritedMembers, ...ownMembers];
+}
+
+function getInheritedMembers(
+	apiItem: ApiItem,
+	extendsType: HeritageType,
+	config: ApiItemTransformationConfiguration,
+): InheritedTypeMember[] {
+	const referencedItem = resolveHeritageTypeToItem(apiItem, extendsType, config);
+	if (referencedItem === undefined || !isTypeLike(referencedItem)) {
+		return [];
+	}
+	const referencedItemMembers: InheritedTypeMember[] = getTypeMembers(
+		referencedItem,
+		config,
+	).map((inherited) => ({
+		kind: "inherited",
+		item: inherited.item,
+		// If the item we're inheriting is itself inherited, preserve the original source.
+		// Otherwise, the source is the item we're inheriting from.
+		baseDefinition: inherited.kind === "inherited" ? inherited.baseDefinition : referencedItem,
+	}));
+
+	// Don't inherit constructors or static members
+	return referencedItemMembers.filter((inherited) => {
+		const itemKind = getApiItemKind(inherited.item);
+		if (itemKind === ApiItemKind.Constructor || itemKind === ApiItemKind.ConstructSignature) {
+			return false;
+		}
+		if (isStatic(inherited.item)) {
+			return false;
+		}
+		return true;
+	});
+}
+
+function resolveHeritageTypeToItem(
+	contextApiItem: ApiItem,
+	heritageType: HeritageType,
+	config: ApiItemTransformationConfiguration,
+): ApiItem | undefined {
+	const excerpt = heritageType.excerpt;
+	if (excerpt.spannedTokens.length === 0) {
+		return undefined;
+	}
+
+	if (excerpt.spannedTokens.length > 1) {
+		// If there are multiple tokens, then the type expression is more complex than a single reference.
+		// This is a case we don't currently support.
+		return undefined;
+	}
+
+	const token = excerpt.spannedTokens[0];
+	if (token.kind !== "Reference" || token.canonicalReference === undefined) {
+		// If the single token is not a reference, then there is nothing to resolve.
+		return undefined;
+	}
+
+	const resolvedReference = config.apiModel.resolveDeclarationReference(
+		token.canonicalReference,
+		contextApiItem,
+	);
+
+	return resolvedReference.resolvedApiItem;
+}

tools/api-markdown-documenter/src/api-item-transforms/utilities/index.ts

@@ -14,4 +14,8 @@ export {
 	shouldItemBeIncluded,
 } from "./ApiItemTransformUtilities.js";
 export { createDocument, checkForDuplicateDocumentPaths } from "./DocumentUtilities.js";
+export {
+	getTypeMembers,
+	type TypeMember,
+} from "./InheritanceUtilities.js";
 export { resolveSymbolicLink } from "./ReferenceUtilities.js";