Skip to content

Commit cc67800

Browse files
sebastian-lenzsebastian-lenz
committed
Added module and dynamic module comments, resolves #20 
1 parent c1ef339 commit cc67800

File tree

10 files changed

+232
-8
lines changed

10 files changed

+232
-8
lines changed

‎examples/basic/run‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
#!/bin/sh
2+
cd ${0%/*}
3+
node ../../bin/typedoc --module commonjs --out doc/ src/

‎examples/self/run‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,3 @@
11
#!/bin/sh
22
cd ${0%/*}
3-
node ../../bin/typedoc --module commonjs --includeDeclarations --externalPattern **/lib/** --verbose --name "TypeDoc Documentation" --out doc/ ../../src/
4-
-
3+
node ../../bin/typedoc --module commonjs --includeDeclarations --externalPattern **/lib/** --excludeExternals --verbose --name "TypeDoc Documentation" --out doc/ ../../src/

‎src/typedoc/Application.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,10 @@
1+
/**
2+
* The TypeDoc main module and namespace.
3+
*
4+
* The [[Application]] class holds the core logic of the cli application. All code related
5+
* to resolving reflections is stored in [[TypeDoc.Factories]], the actual data models can be found
6+
* in [[TypeDoc.Models]] and the final rendering is defined in [[TypeDoc.Output]].
7+
*/
18
module TypeDoc
29
{
310
/**

‎src/typedoc/factories/Dispatcher.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
/**
2+
* Holds all logic used to analyze the output of the TypeScript compiler and generate reflections.
3+
*
4+
* The [[Dispatcher]] class is the central controller within this namespace. When invoked it fires a
5+
* series of [[DispatcherEvent]] events consumed by [[BaseHandler]] instances.
6+
*/
17
module TypeDoc.Factories
28
{
39
/**

‎src/typedoc/factories/handlers/DynamicModuleHandler.ts‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,11 @@ module TypeDoc.Factories
66
*/
77
export class DynamicModuleHandler extends BaseHandler
88
{
9+
/**
10+
* The ast walker factory.
11+
*/
12+
private factory:TypeScript.AstWalkerFactory;
13+
914
/**
1015
* Helper class for determining the base path.
1116
*/
@@ -33,6 +38,8 @@ module TypeDoc.Factories
3338
constructor(dispatcher:Dispatcher) {
3439
super(dispatcher);
3540

41+
this.factory = TypeScript.getAstWalkerFactory();
42+
3643
dispatcher.on(Dispatcher.EVENT_BEGIN, this.onBegin, this);
3744
dispatcher.on(Dispatcher.EVENT_DECLARATION, this.onDeclaration, this);
3845
dispatcher.on(Dispatcher.EVENT_BEGIN_RESOLVE, this.onBeginResolve, this);
@@ -65,6 +72,26 @@ module TypeDoc.Factories
6572
name = name.replace(/"/g, '');
6673
this.reflections.push(state.reflection);
6774
this.basePath.add(name);
75+
76+
var ast = <TypeScript.SourceUnit>state.declaration.ast();
77+
if (ast instanceof TypeScript.SourceUnit) {
78+
var resolved = false;
79+
this.factory.simpleWalk(ast, (ast:TypeScript.AST, astState:any) => {
80+
if (resolved ||
81+
ast.kind() == TypeScript.SyntaxKind.SourceUnit ||
82+
ast.kind() == TypeScript.SyntaxKind.List)
83+
{
84+
return;
85+
}
86+
87+
var comments = ast.preComments();
88+
if (comments && comments.length > 1 && CommentHandler.isDocComment(comments[0])) {
89+
state.reflection.comment = CommentHandler.parseDocComment(comments[0].fullText());
90+
}
91+
92+
resolved = true;
93+
});
94+
}
6895
}
6996
}
7097

src/typedoc/factories/handlers/AstHandler.ts renamed to src/typedoc/factories/handlers/ExportHandler.ts

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -25,9 +25,9 @@ module TypeDoc.Factories
2525

2626

2727
/**
28-
* A handler that analyzes the AST and extracts data not represented by declarations.
28+
* A handler that analyzes and resolves export statements of dynamic modules.
2929
*/
30-
export class AstHandler extends BaseHandler
30+
export class ExportHandler extends BaseHandler
3131
{
3232
/**
3333
* The ast walker factory.
@@ -114,7 +114,7 @@ module TypeDoc.Factories
114114
});
115115

116116
state.reflection.kind = state.declaration.kind;
117-
AstHandler.markAsExported(state.reflection);
117+
ExportHandler.markAsExported(state.reflection);
118118

119119
this.exports.push({
120120
name: state.declaration.name,
@@ -184,13 +184,13 @@ module TypeDoc.Factories
184184
*/
185185
static markAsExported(reflection:Models.DeclarationReflection) {
186186
reflection.flags = reflection.flags | TypeScript.PullElementFlags.Exported;
187-
reflection.children.forEach((child) => AstHandler.markAsExported(child));
187+
reflection.children.forEach((child) => ExportHandler.markAsExported(child));
188188
}
189189
}
190190

191191

192192
/**
193193
* Register this handler.
194194
*/
195-
Dispatcher.HANDLERS.push(AstHandler);
195+
Dispatcher.HANDLERS.push(ExportHandler);
196196
}

‎src/typedoc/factories/handlers/ModuleCommentHandler.ts‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
module TypeDoc.Factories
2+
{
3+
/**
4+
* Structure used by [[ContainerCommentHandler]] to store discovered module comments.
5+
*/
6+
interface IModuleComment
7+
{
8+
/**
9+
* The module reflection this comment is targeting.
10+
*/
11+
reflection:Models.DeclarationReflection;
12+
13+
/**
14+
* The full text of the best matched comment.
15+
*/
16+
fullText:string;
17+
18+
/**
19+
* Has the full text been marked as being preferred?
20+
*/
21+
isPreferred:boolean;
22+
}
23+
24+
25+
/**
26+
* A handler that extracts comments of containers like modules.
27+
*
28+
* The [[CommentHandler]] only extracts comments directly attached to the current
29+
* declaration, while this handler looks up the comments of the parent ast of the given
30+
* declaration if it is some container. As modules might be defined multiple times,
31+
* this handler stores the found comments and applies them in the resolving phase.
32+
*
33+
* If multiple comments for the same module are found, the longest comment will be preferred.
34+
* One may explicitly set the preferred module comment by appending the tag `@preferred`.
35+
*/
36+
export class ModuleCommentHandler extends BaseHandler
37+
{
38+
/**
39+
* The ast walker factory.
40+
*/
41+
private factory:TypeScript.AstWalkerFactory;
42+
43+
/**
44+
* List of discovered module comments.
45+
*/
46+
private comments:{[id:number]:IModuleComment};
47+
48+
49+
/**
50+
* Create a new ModuleCommentHandler instance.
51+
*
52+
* @param dispatcher The dispatcher this handler should be attached to.
53+
*/
54+
constructor(dispatcher:Dispatcher) {
55+
super(dispatcher);
56+
57+
this.factory = TypeScript.getAstWalkerFactory();
58+
59+
dispatcher.on(Dispatcher.EVENT_BEGIN, this.onBegin, this);
60+
dispatcher.on(Dispatcher.EVENT_DECLARATION, this.onDeclaration, this);
61+
dispatcher.on(Dispatcher.EVENT_BEGIN_RESOLVE, this.onBeginResolve, this);
62+
}
63+
64+
65+
/**
66+
* Triggered once per project before the dispatcher invokes the compiler.
67+
*
68+
* @param event An event object containing the related project and compiler instance.
69+
*/
70+
private onBegin(event:DispatcherEvent) {
71+
this.comments = {};
72+
}
73+
74+
75+
/**
76+
* Triggered when the dispatcher processes a declaration.
77+
*
78+
* @param state The state that describes the current declaration and reflection.
79+
*/
80+
private onDeclaration(state:DeclarationState) {
81+
if (!state.kindOf(TypeScript.PullElementKind.Container)) {
82+
return;
83+
}
84+
85+
var ast = state.declaration.ast();
86+
ast = ast.parent;
87+
if (ast && ast.kind() == TypeScript.SyntaxKind.QualifiedName) {
88+
var identifiers = [];
89+
this.factory.simpleWalk(ast, (ast:TypeScript.AST, astState:any) => {
90+
if (ast.kind() == TypeScript.SyntaxKind.IdentifierName) {
91+
identifiers.push(ast);
92+
}
93+
});
94+
95+
if (identifiers.indexOf(state.declaration.ast()) < identifiers.length - 1) {
96+
return;
97+
}
98+
99+
while (ast && ast.kind() == TypeScript.SyntaxKind.QualifiedName) {
100+
ast = ast.parent;
101+
}
102+
}
103+
104+
if (!ast || ast.kind() != TypeScript.SyntaxKind.ModuleDeclaration) {
105+
return;
106+
}
107+
108+
var comments = ast.preComments();
109+
if (!comments || comments.length == 0) {
110+
return;
111+
}
112+
113+
var comment = comments[comments.length -1];
114+
if (!CommentHandler.isDocComment(comment)) {
115+
return;
116+
}
117+
118+
var fullText = comment.fullText();
119+
var isPreferred = (fullText.toLowerCase().indexOf('@preferred') != -1);
120+
121+
if (this.comments[state.reflection.id]) {
122+
var info = this.comments[state.reflection.id];
123+
if (!isPreferred && (info.isPreferred || info.fullText.length > fullText.length)) {
124+
return;
125+
}
126+
127+
info.fullText = fullText;
128+
info.isPreferred = isPreferred;
129+
} else {
130+
this.comments[state.reflection.id] = {
131+
reflection: state.reflection,
132+
fullText: fullText,
133+
isPreferred: isPreferred
134+
};
135+
}
136+
}
137+
138+
139+
/**
140+
* Triggered when the dispatcher enters the resolving phase.
141+
*
142+
* @param event An event object containing the related project and compiler instance.
143+
*/
144+
private onBeginResolve(event:DispatcherEvent) {
145+
for (var id in this.comments) {
146+
if (!this.comments.hasOwnProperty(id)) {
147+
continue;
148+
}
149+
150+
var info = this.comments[id];
151+
var comment = CommentHandler.parseDocComment(info.fullText);
152+
CommentHandler.removeTags(comment, 'preferred');
153+
154+
info.reflection.comment = comment;
155+
}
156+
}
157+
}
158+
159+
160+
/**
161+
* Register this handler.
162+
*/
163+
Dispatcher.HANDLERS.push(ModuleCommentHandler);
164+
}

‎src/typedoc/factories/handlers/ReflectionHandler.ts‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -243,7 +243,6 @@ module TypeDoc.Factories
243243

244244

245245
/**
246-
*
247246
* Applied when a container is merged with a variable.
248247
*
249248
* @param state

‎src/typedoc/models/reflections/BaseReflection.ts‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,14 @@
1+
/**
2+
* Holds all data models used by TypeDoc.
3+
*
4+
* The [[BaseReflection]] is base class of all reflection models. The subclass [[ProjectReflection]]
5+
* serves as the root container for the current project while [[DeclarationReflection]] instances
6+
* form the structure of the project. Most of the other classes in this namespace are referenced by this
7+
* two base classes.
8+
*
9+
* The models [[NavigationItem]] and [[UrlMapping]] are special as they are only used by the [[Renderer]]
10+
* while creating the final output.
11+
*/
112
module TypeDoc.Models
213
{
314
/**

‎src/typedoc/output/Renderer.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,11 @@
1+
/**
2+
* Holds all logic used render and output the final documentation.
3+
*
4+
* The [[Renderer]] class is the central controller within this namespace. When invoked it creates
5+
* an instance of [[BaseTheme]] which defines the layout of the documentation and fires a
6+
* series of [[OutputEvent]] events. Instances of [[BasePlugin]] can listen to these events and
7+
* alter the generated output.
8+
*/
19
module TypeDoc.Output
210
{
311
/**

0 commit comments

Comments
 (0)