Skip to content

Commit 7918fba

Browse files
Gerrit0Gerrit0
committed
Correct behavior of excludeNotDocumented
Resolves #1752 Resolves #1948
1 parent 3edb447 commit 7918fba

File tree

9 files changed

+1232
-170
lines changed

9 files changed

+1232
-170
lines changed

‎CHANGELOG.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ These TODOs will be resolved before a full release. ([GitHub project](https://gi
1313

1414
- Node 12 is no longer officially supported as it has gone end of life as of 2022-04-30. It might still work, but may stop working at any time.
1515
- Dropped support for TypeScript before 4.6.
16+
- TypeDoc will now produce warnings for bracketed links (`[[ target ]]`). Use `{@link target}` instead. The `{@link}` syntax will be recognized by [TypeScript 4.3](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-3.html#editor-support-for-link-tags) and later and used to provide better intellisense. TypeDoc version 0.24.0 will remove support for `[[ target ]]` style links.
1617
- `extends` in typedoc.json is now resolved using NodeJS module resolution, so a local path must begin with `./`.
1718
- In the JSON output for `DeclarationReflection`s, `getSignature` is no longer a one-tuple.
1819
- In the JSON output for `DeclarationReflection`s, `setSignature` is no longer a one-tuple.
@@ -23,7 +24,6 @@ These TODOs will be resolved before a full release. ([GitHub project](https://gi
2324
- The deprecated `listInvalidSymbolLinks` option has been removed. Use `validation.invalidLink` instead.
2425
- The deprecated `true` and `false` values have been removed from `--emit`, to migrate replace `true` with `"both"` and `false` with `"docs"`.
2526
- Links are no longer be resolved against a global list of all symbols. See [the documentation](https://typedoc.org/guides/link-resolution/) for details on link resolution.
26-
- TypeDoc will now produce warnings for bracketed links (`[[ target ]]`). Use `{@link target}` instead. The `{@link}` syntax will be recognized by [TypeScript 4.3](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-3.html#editor-support-for-link-tags) and later and used to provide better intellisense. TypeDoc version 0.24.0 will remove support for `[[ target ]]` style links.
2727
- The `validation.invalidLink` option is now on by default.
2828
- `reflection.decorates`, `reflection.decorators`, and their corresponding interfaces have been removed as no code in TypeDoc used them.
2929
- The shape of the `Comment` class has changed significantly to support multiple tag kinds.
@@ -68,6 +68,8 @@ These TODOs will be resolved before a full release. ([GitHub project](https://gi
6868
- TypeDoc will now automatically inherit documentation from classes `implements` by other interfaces/classes.
6969
- Fixed `@inheritDoc` on accessors, #1927.
7070
- JS exports defined as `exports.foo = ...` will now be converted as variables rather than properties.
71+
- The `excludeNotDocumented` option will no longer hide a module if it has a documentation comment, #1948.
72+
- Prevent `--excludeNotDocumented` from hiding properties of type literals (`a` in `function fn(p: { a: string })`), #1752.
7173
- Corrected schema generation for https://typedoc.org/schema.json
7274

7375
### Thanks!

‎src/lib/converter/context.ts

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -240,7 +240,7 @@ export class Context {
240240
}
241241

242242
shouldIgnore(symbol: ts.Symbol) {
243-
return this.converter.shouldIgnore(symbol, this.checker);
243+
return this.converter.shouldIgnore(symbol);
244244
}
245245

246246
/**

‎src/lib/converter/converter.ts

Lines changed: 10 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,6 @@ import { convertSymbol } from "./symbols";
1212
import { createMinimatch, matchesAny } from "../utils/paths";
1313
import type { IMinimatch } from "minimatch";
1414
import { hasAllFlags, hasAnyFlag } from "../utils/enum";
15-
import { resolveAliasedSymbol } from "./utils/symbols";
1615
import type { DocumentationEntryPoint } from "../utils/entry-point";
1716
import type { CommentParserConfig } from "./comments";
1817

@@ -224,11 +223,9 @@ export class Converter extends ChildableComponent<
224223

225224
const allExports = getExports(context, node, symbol);
226225

227-
if (
228-
allExports.every((exp) => this.shouldIgnore(exp, context.checker))
229-
) {
226+
if (allExports.every((exp) => this.shouldIgnore(exp))) {
230227
this.owner.logger.verbose(
231-
`Ignoring entry point ${entryName} since all members will be ignored.`
228+
`All members of ${entryName} are excluded, ignoring entry point.`
232229
);
233230
return;
234231
}
@@ -292,28 +289,18 @@ export class Converter extends ChildableComponent<
292289
this.trigger(Converter.EVENT_RESOLVE_END, context);
293290
}
294291

295-
/** @internal */
296-
shouldIgnore(symbol: ts.Symbol, checker: ts.TypeChecker) {
297-
if (
298-
this.excludeNotDocumented &&
299-
// If the enum is included, we should include members even if not documented.
300-
!hasAllFlags(symbol.flags, ts.SymbolFlags.EnumMember) &&
301-
resolveAliasedSymbol(symbol, checker).getDocumentationComment(
302-
checker
303-
).length === 0
304-
) {
305-
return true;
306-
}
307-
292+
/**
293+
* Used to determine if we should immediately bail when creating a reflection.
294+
* Note: This should not be used for excludeNotDocumented because we don't have enough
295+
* information at this point since comment discovery hasn't happened.
296+
* @internal
297+
*/
298+
shouldIgnore(symbol: ts.Symbol) {
308299
if (this.isExcluded(symbol)) {
309300
return true;
310301
}
311302

312-
if (!this.excludeExternals) {
313-
return false;
314-
}
315-
316-
return this.isExternal(symbol);
303+
return this.excludeExternals && this.isExternal(symbol);
317304
}
318305

319306
private isExcluded(symbol: ts.Symbol) {

‎src/lib/converter/plugins/CommentPlugin.ts

Lines changed: 38 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,9 @@ export class CommentPlugin extends ConverterComponent {
6363
@BindOption("excludeProtected")
6464
excludeProtected!: boolean;
6565

66+
@BindOption("excludeNotDocumented")
67+
excludeNotDocumented!: boolean;
68+
6669
/**
6770
* Create a new CommentPlugin instance.
6871
*/
@@ -375,7 +378,7 @@ export class CommentPlugin extends ConverterComponent {
375378
*
376379
* @param reflection Reflection to check if hidden
377380
*/
378-
private isHidden(reflection: Reflection) {
381+
private isHidden(reflection: Reflection): boolean {
379382
const comment = reflection.comment;
380383

381384
if (
@@ -393,6 +396,30 @@ export class CommentPlugin extends ConverterComponent {
393396
}
394397

395398
if (!comment) {
399+
if (this.excludeNotDocumented) {
400+
// Only allow excludeNotDocumented to exclude root level reflections
401+
if (!(reflection instanceof DeclarationReflection)) {
402+
return false;
403+
}
404+
405+
// excludeNotDocumented should hide a module only if it has no visible children
406+
if (reflection.kindOf(ReflectionKind.SomeModule)) {
407+
if (!reflection.children) {
408+
return true;
409+
}
410+
return reflection.children.every((child) =>
411+
this.isHidden(child)
412+
);
413+
}
414+
415+
// enum members should all be included if the parent enum is documented
416+
if (reflection.kind === ReflectionKind.EnumMember) {
417+
return false;
418+
}
419+
420+
// excludeNotDocumented should never hide parts of "type" reflections
421+
return inTypeLiteral(reflection) === false;
422+
}
396423
return false;
397424
}
398425

@@ -404,6 +431,16 @@ export class CommentPlugin extends ConverterComponent {
404431
}
405432
}
406433

434+
function inTypeLiteral(refl: Reflection | undefined) {
435+
while (refl) {
436+
if (refl.kind === ReflectionKind.TypeLiteral) {
437+
return true;
438+
}
439+
refl = refl.parent;
440+
}
441+
return false;
442+
}
443+
407444
// Moves tags like `@param foo.bar docs for bar` into the `bar` property of the `foo` parameter.
408445
function moveNestedParamTags(comment: Comment, parameter: ParameterReflection) {
409446
const visitor: Partial<TypeVisitor> = {

‎src/lib/converter/symbols.ts

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -336,8 +336,7 @@ function convertTypeAlias(
336336
context.finalizeDeclarationReflection(reflection);
337337

338338
// Do this after finalization so that the CommentPlugin can get @typeParam tags
339-
// from the parent comment. Ugly, but works for now. Should be cleaned up with TSDoc
340-
// support.
339+
// from the parent comment. Ugly, but works for now. Should be cleaned up eventually.
341340
reflection.typeParameters = declaration.typeParameters?.map((param) =>
342341
createTypeParamReflection(param, context.withScope(reflection))
343342
);

‎src/test/converter/exports/no-doc-members.ts

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
/**
2+
* This module has documentation, but no exported members do.
3+
* @see https://github.com/TypeStrong/typedoc/issues/1948
4+
* @module
5+
*/
6+
export const abc = 123;

‎src/test/converter/exports/specs.json

Lines changed: 105 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212
"flags": {},
1313
"children": [
1414
{
15-
"id": 46,
15+
"id": 48,
1616
"name": "GH1453Helper",
1717
"kind": 8388608,
1818
"kindString": "Reference",
@@ -28,7 +28,7 @@
2828
"target": 35
2929
},
3030
{
31-
"id": 39,
31+
"id": 41,
3232
"name": "Mod",
3333
"kind": 8388608,
3434
"kindString": "Reference",
@@ -44,7 +44,7 @@
4444
"target": 29
4545
},
4646
{
47-
"id": 41,
47+
"id": 43,
4848
"name": "Mod2",
4949
"kind": 8388608,
5050
"kindString": "Reference",
@@ -68,7 +68,7 @@
6868
"target": 29
6969
},
7070
{
71-
"id": 40,
71+
"id": 42,
7272
"name": "ModDefault",
7373
"kind": 8388608,
7474
"kindString": "Reference",
@@ -84,7 +84,7 @@
8484
"target": 36
8585
},
8686
{
87-
"id": 45,
87+
"id": 47,
8888
"name": "ThisModule",
8989
"kind": 8388608,
9090
"kindString": "Reference",
@@ -100,7 +100,7 @@
100100
"target": 34
101101
},
102102
{
103-
"id": 42,
103+
"id": 44,
104104
"name": "a",
105105
"kind": 8388608,
106106
"kindString": "Reference",
@@ -116,7 +116,7 @@
116116
"target": 30
117117
},
118118
{
119-
"id": 43,
119+
"id": 45,
120120
"name": "b",
121121
"kind": 8388608,
122122
"kindString": "Reference",
@@ -140,7 +140,7 @@
140140
"target": 31
141141
},
142142
{
143-
"id": 38,
143+
"id": 40,
144144
"name": "c",
145145
"kind": 8388608,
146146
"kindString": "Reference",
@@ -398,14 +398,14 @@
398398
{
399399
"title": "References",
400400
"children": [
401-
46,
402-
39,
401+
48,
403402
41,
404-
40,
405-
45,
406-
42,
407403
43,
408-
38
404+
42,
405+
47,
406+
44,
407+
45,
408+
40
409409
]
410410
},
411411
{
@@ -853,6 +853,95 @@
853853
"url": "https://github.com/TypeStrong/typedoc/blob/fake/src/test/converter/exports/mod.ts#L8"
854854
}
855855
]
856+
},
857+
{
858+
"id": 38,
859+
"name": "no-doc-members",
860+
"kind": 2,
861+
"kindString": "Module",
862+
"flags": {},
863+
"comment": {
864+
"summary": [
865+
{
866+
"kind": "text",
867+
"text": "This module has documentation, but no exported members do."
868+
}
869+
],
870+
"blockTags": [
871+
{
872+
"tag": "@see",
873+
"content": [
874+
{
875+
"kind": "text",
876+
"text": "https://github.com/TypeStrong/typedoc/issues/1948"
877+
}
878+
]
879+
}
880+
]
881+
},
882+
"children": [
883+
{
884+
"id": 39,
885+
"name": "abc",
886+
"kind": 32,
887+
"kindString": "Variable",
888+
"flags": {
889+
"isConst": true
890+
},
891+
"comment": {
892+
"summary": [
893+
{
894+
"kind": "text",
895+
"text": "This module has documentation, but no exported members do."
896+
}
897+
],
898+
"blockTags": [
899+
{
900+
"tag": "@see",
901+
"content": [
902+
{
903+
"kind": "text",
904+
"text": "https://github.com/TypeStrong/typedoc/issues/1948"
905+
}
906+
]
907+
},
908+
{
909+
"tag": "@module",
910+
"content": []
911+
}
912+
]
913+
},
914+
"sources": [
915+
{
916+
"fileName": "no-doc-members.ts",
917+
"line": 6,
918+
"character": 13,
919+
"url": "https://github.com/TypeStrong/typedoc/blob/fake/src/test/converter/exports/no-doc-members.ts#L6"
920+
}
921+
],
922+
"type": {
923+
"type": "literal",
924+
"value": 123
925+
},
926+
"defaultValue": "123"
927+
}
928+
],
929+
"groups": [
930+
{
931+
"title": "Variables",
932+
"children": [
933+
39
934+
]
935+
}
936+
],
937+
"sources": [
938+
{
939+
"fileName": "no-doc-members.ts",
940+
"line": 6,
941+
"character": 0,
942+
"url": "https://github.com/TypeStrong/typedoc/blob/fake/src/test/converter/exports/no-doc-members.ts#L6"
943+
}
944+
]
856945
}
857946
],
858947
"groups": [
@@ -863,7 +952,8 @@
863952
1,
864953
6,
865954
8,
866-
29
955+
29,
956+
38
867957
]
868958
}
869959
]

0 commit comments

Comments
 (0)