Skip to content

Commit a68c3bb

Browse files
committed
Support comments on source declarations in more cases
This seems like a reasonable tradeoff between allowing doc comments to be placed on members which are otherwise undocumentable and avoiding issues with functions where comments on the export declaration would only partially override the comments due to `@param` comments being present on the parameters very early. Resolves #2964
1 parent e229822 commit a68c3bb

File tree

5 files changed

+85
-2
lines changed

5 files changed

+85
-2
lines changed

CHANGELOG.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ title: Changelog
77
### Features
88

99
- TypeDoc now supports resolving relative paths in links to the package directory as belonging to the project, #2961.
10+
- Declarations without comments will now check for comments on their export specifier, #2964.
1011

1112
### Bug Fixes
1213

site/doc-comments/index.md

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,54 @@ Will be rendered as:
7979
> function example(): void;
8080
> ```
8181
82+
## Comment Discovery
83+
84+
In most cases, TypeDoc's comment discovery closely mirrors TypeScript's discovery. If a comment is placed
85+
directly before a declaration or typically belongs to a declaration but lives on a parent node, TypeDoc
86+
will include it in the documentation.
87+
88+
```ts
89+
/**
90+
* This works
91+
* @param x this works
92+
*/
93+
function example(x: string, /** This too */ y: number) {}
94+
/** This also works */
95+
class Example2 {}
96+
```
97+
98+
TypeDoc also supports discovering comments in some locations which TypeScript does not.
99+
100+
1. Comments on type aliases directly containing unions may have comments before each union branch
101+
to document the union.
102+
103+
```ts
104+
type Choices =
105+
/** Comment for option 1 */
106+
| "option_1"
107+
/** Comment for option 2 */
108+
| { option_1: number };
109+
```
110+
111+
2. Comments on export specifiers which export (or re-export) a member.
112+
113+
```ts
114+
/** A comment here will take precedence over a module comment in Lib */
115+
export * as Lib from "lib";
116+
```
117+
118+
Comments on export specifiers only have higher priority than the module comment for modules
119+
and references where the symbol appears in the documentation multiple times.
120+
121+
```ts
122+
export * as Lib from "lib"; // Use the @module comment
123+
/** Preserved for backwards compatibility, prefer {@link Lib} */
124+
export * as Library from "lib";
125+
126+
/** This comment will be used for someFunction only if someFunction does not have a comment directly on it */
127+
export { someFunction } from "lib";
128+
```
129+
82130
## See Also
83131

84132
- The [Tags overview](../tags.md)

src/lib/converter/context.ts

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -189,18 +189,30 @@ export class Context {
189189
symbol: ts.Symbol | undefined,
190190
exportSymbol: ts.Symbol | undefined,
191191
) {
192+
// Allow comments on export declarations to take priority over comments directly
193+
// on the symbol to enable overriding comments on modules/references, #1504
192194
if (
193195
!reflection.comment &&
194196
exportSymbol &&
195-
reflection.kind &
196-
(ReflectionKind.SomeModule | ReflectionKind.Reference)
197+
(reflection.kind &
198+
(ReflectionKind.SomeModule | ReflectionKind.Reference))
197199
) {
198200
reflection.comment = this.getComment(exportSymbol, reflection.kind);
199201
}
202+
203+
// If that didn't get us a comment (the normal case), then get the comment from
204+
// the source declarations, this is the common case.
200205
if (symbol && !reflection.comment) {
201206
reflection.comment = this.getComment(symbol, reflection.kind);
202207
}
203208

209+
// If we still don't have a comment, check for any comments on the export declaration,
210+
// we don't have to worry about functions being weird in this case as the regular declaration
211+
// doesn't have any comment.
212+
if (exportSymbol && !reflection.comment) {
213+
reflection.comment = this.getComment(exportSymbol, ReflectionKind.Reference);
214+
}
215+
204216
if (this.shouldBeStatic) {
205217
reflection.setFlag(ReflectionFlag.Static);
206218
}
Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
declare module "*.gh2964" {
2+
export const data: "string";
3+
}
4+
5+
/** @ignore */
6+
export { data as first } from "test.gh2964";
7+
/** @ignore */
8+
export { data as second } from "test.gh2964";
9+
10+
/** Comment on variable */
11+
const third: "not ignored";
12+
/** @ignore -- does not work as third has a comment */
13+
export { third };
14+
15+
const fourth: "ignored";
16+
/** @ignore -- works as fourth does not have a comment */
17+
export { fourth };

src/test/issues.c2.test.ts

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2121,4 +2121,9 @@ describe("Issue Tests", () => {
21212121
equal(query(project, "Func").type?.toString(), "(a: T) => void");
21222122
equal(query(project, "Var").type?.toString(), "123");
21232123
});
2124+
2125+
it("#2964 handles ignored instances of wildcard declared modules", () => {
2126+
const project = convert();
2127+
equal(project.children?.map(c => c.name), ["third"]);
2128+
});
21242129
});

0 commit comments

Comments
 (0)