diff --git a/CHANGELOG.md b/CHANGELOG.md index eaedd2331..fe7b6cfec 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,27 @@ # Unreleased +### Breaking Changes + +- Upgraded Shiki, if your highlight theme was set to `material-`, the value will need to be changed to + `material-theme-`, see the [Shiki release notes](https://github.com/shikijs/shiki/blob/main/CHANGELOG.md#0130--2023-01-27). + +### Features + +- Added new `excludeNotDocumentedKinds` variable to control which reflection types can be removed + by the `excludeNotDocumented` option, #2162. +- Added `typedoc.jsonc`, `typedoc.config.js`, `typedoc.config.cjs`, `typedoc.cjs` to the list of files + which TypeDoc will automatically use as configuration files. + +### Bug Fixes + +- Entry points under `node_modules` will no longer be ignored, #2151. + +### Thanks! + +- @boneskull +- @Mikkal24 +- @zamiell + ## v0.23.24 (2023-01-07) ### Bug Fixes diff --git a/src/lib/converter/plugins/CommentPlugin.ts b/src/lib/converter/plugins/CommentPlugin.ts index 899611e1a..aeec28177 100644 --- a/src/lib/converter/plugins/CommentPlugin.ts +++ b/src/lib/converter/plugins/CommentPlugin.ts @@ -118,6 +118,14 @@ export class CommentPlugin extends ConverterComponent { @BindOption("excludeNotDocumented") excludeNotDocumented!: boolean; + private _excludeKinds: number | undefined; + private get excludeNotDocumentedKinds(): number { + this._excludeKinds ??= this.application.options + .getValue("excludeNotDocumentedKinds") + .reduce((a, b) => a | ReflectionKind[b], 0); + return this._excludeKinds; + } + /** * Create a new CommentPlugin instance. */ @@ -128,6 +136,9 @@ export class CommentPlugin extends ConverterComponent { [Converter.EVENT_CREATE_TYPE_PARAMETER]: this.onCreateTypeParameter, [Converter.EVENT_RESOLVE_BEGIN]: this.onBeginResolve, [Converter.EVENT_RESOLVE]: this.onResolve, + [Converter.EVENT_END]: () => { + this._excludeKinds = undefined; + }, }); } @@ -462,6 +473,10 @@ export class CommentPlugin extends ConverterComponent { return false; } + if (!reflection.kindOf(this.excludeNotDocumentedKinds)) { + return false; + } + // excludeNotDocumented should hide a module only if it has no visible children if (reflection.kindOf(ReflectionKind.SomeModule)) { if (!(reflection as DeclarationReflection).children) { @@ -472,11 +487,6 @@ export class CommentPlugin extends ConverterComponent { ).children!.every((child) => this.isHidden(child)); } - // enum members should all be included if the parent enum is documented - if (reflection.kind === ReflectionKind.EnumMember) { - return false; - } - // signature containers should only be hidden if all their signatures are hidden if (reflection.kindOf(ReflectionKind.SignatureContainer)) { return (reflection as DeclarationReflection) diff --git a/src/lib/utils/options/declaration.ts b/src/lib/utils/options/declaration.ts index 4faffd395..bb49ce214 100644 --- a/src/lib/utils/options/declaration.ts +++ b/src/lib/utils/options/declaration.ts @@ -85,6 +85,7 @@ export interface TypeDocOptionMap { externalPattern: string[]; excludeExternals: boolean; excludeNotDocumented: boolean; + excludeNotDocumentedKinds: Array; excludeInternal: boolean; excludePrivate: boolean; excludeProtected: boolean; diff --git a/src/lib/utils/options/sources/typedoc.ts b/src/lib/utils/options/sources/typedoc.ts index dcc7d50da..5272c24e3 100644 --- a/src/lib/utils/options/sources/typedoc.ts +++ b/src/lib/utils/options/sources/typedoc.ts @@ -85,6 +85,58 @@ export function addTypeDocOptions(options: Pick) { help: "Prevent symbols that are not explicitly documented from appearing in the results.", type: ParameterType.Boolean, }); + options.addDeclaration({ + name: "excludeNotDocumentedKinds", + help: "Specify the type of reflections that can be removed by excludeNotDocumented.", + type: ParameterType.Array, + validate(value) { + const invalid = new Set(value); + const valid = new Set(getEnumKeys(ReflectionKind)); + for (const notPermitted of [ + ReflectionKind.Project, + ReflectionKind.TypeLiteral, + ReflectionKind.TypeParameter, + ReflectionKind.Parameter, + ReflectionKind.ObjectLiteral, + ]) { + valid.delete(ReflectionKind[notPermitted]); + } + for (const v of valid) { + invalid.delete(v); + } + + if (invalid.size !== 0) { + throw new Error( + `excludeNotDocumentedKinds may only specify known values, and invalid values were provided (${Array.from( + invalid + ).join(", ")}). The valid kinds are:\n${Array.from( + valid + ).join(", ")}` + ); + } + }, + defaultValue: [ + ReflectionKind[ReflectionKind.Module], + ReflectionKind[ReflectionKind.Namespace], + ReflectionKind[ReflectionKind.Enum], + // Not including enum member here by default + ReflectionKind[ReflectionKind.Variable], + ReflectionKind[ReflectionKind.Function], + ReflectionKind[ReflectionKind.Class], + ReflectionKind[ReflectionKind.Interface], + ReflectionKind[ReflectionKind.Constructor], + ReflectionKind[ReflectionKind.Property], + ReflectionKind[ReflectionKind.Method], + ReflectionKind[ReflectionKind.CallSignature], + ReflectionKind[ReflectionKind.IndexSignature], + ReflectionKind[ReflectionKind.ConstructorSignature], + ReflectionKind[ReflectionKind.Accessor], + ReflectionKind[ReflectionKind.GetSignature], + ReflectionKind[ReflectionKind.SetSignature], + ReflectionKind[ReflectionKind.TypeAlias], + ReflectionKind[ReflectionKind.Reference], + ], + }); options.addDeclaration({ name: "excludeInternal", help: "Prevent symbols that are marked with @internal from being documented.", @@ -631,16 +683,16 @@ export function addTypeDocOptions(options: Pick) { } }, defaultValue: [ - "Enum", - "EnumMember", - "Variable", - "Function", - "Class", - "Interface", - "Property", - "Method", - "Accessor", - "TypeAlias", + ReflectionKind[ReflectionKind.Enum], + ReflectionKind[ReflectionKind.EnumMember], + ReflectionKind[ReflectionKind.Variable], + ReflectionKind[ReflectionKind.Function], + ReflectionKind[ReflectionKind.Class], + ReflectionKind[ReflectionKind.Interface], + ReflectionKind[ReflectionKind.Property], + ReflectionKind[ReflectionKind.Method], + ReflectionKind[ReflectionKind.Accessor], + ReflectionKind[ReflectionKind.TypeAlias], ], }); diff --git a/src/test/behaviorTests.ts b/src/test/behaviorTests.ts index 885ec4ccc..ffca499d0 100644 --- a/src/test/behaviorTests.ts +++ b/src/test/behaviorTests.ts @@ -10,6 +10,7 @@ import { CommentTag, Reflection, SignatureReflection, + ContainerReflection, } from "../lib/models"; import { Chars, filterMap } from "../lib/utils"; import { CommentStyle } from "../lib/utils/options/declaration"; @@ -21,6 +22,20 @@ function query(project: ProjectReflection, name: string) { return reflection; } +type NameTree = { [name: string]: NameTree }; + +function buildNameTree( + refl: ContainerReflection, + tree: NameTree = {} +): NameTree { + for (const child of refl.children || []) { + tree[child.name] ||= {}; + buildNameTree(child, tree[child.name]); + } + + return tree; +} + type Letters = Chars<"abcdefghijklmnopqrstuvwxyz">; export const behaviorTests: { @@ -201,6 +216,19 @@ export const behaviorTests: { logger.expectNoOtherMessages(); }, + _excludeNotDocumentedKinds(app) { + app.options.setValue("excludeNotDocumented", true); + app.options.setValue("excludeNotDocumentedKinds", ["Property"]); + }, + excludeNotDocumentedKinds(project) { + equal(buildNameTree(project), { + NotDoc: { + prop: {}, + }, + identity: {}, + }); + }, + exportComments(project) { const abc = query(project, "abc"); equal(abc.kind, ReflectionKind.Variable); diff --git a/src/test/converter2/behavior/excludeNotDocumentedKinds.ts b/src/test/converter2/behavior/excludeNotDocumentedKinds.ts new file mode 100644 index 000000000..5d0de07c9 --- /dev/null +++ b/src/test/converter2/behavior/excludeNotDocumentedKinds.ts @@ -0,0 +1,11 @@ +export interface NotDoc { + /** Doc */ + prop: 123; + + notDoc: 456; +} + +/** Doc */ +export function identity(x: T): T { + return x; +}