diff --git a/README.md b/README.md index 5ab797aed..29cdade5c 100644 --- a/README.md +++ b/README.md @@ -151,4 +151,44 @@ function doSomething(target:any, value:number):number; function doSomething(target:any, arg:any):number { return 0; } +``` + + +### Modules + +Modules can be commented like any other elements in TypeScript. As modules can be defined in multiple +files, TypeDoc selects the longest comment by default. One may override this behaviour with the special +`@preferred` comment tag. + +```typescript +/** + * Actual module comment. + * @preferred + */ +module MyModule { } +``` + +```typescript +/** + * Dismissed module comment. + * This is the longer comment but will be dismissed in favor of the preferred comment. + */ +module MyModule { } +``` + + +### Dynamic modules + +The first doc comment within a file is used as the doc comment of a dynamic module. However, you must +ensure that the first declaration also has as doc comment. + +```typescript +/** + * This is a doc comment for a dynamic module. + */ + +/** + * This is a doc comment for "someVar". + */ +var someVar:string = "value"; ``` \ No newline at end of file diff --git a/bin/typedoc.d.ts b/bin/typedoc.d.ts index d98f50db7..b30abb259 100644 --- a/bin/typedoc.d.ts +++ b/bin/typedoc.d.ts @@ -834,6 +834,25 @@ declare module TypeDoc.Factories { static parseDocComment(text: string, comment?: Models.Comment): Models.Comment; } } +declare module TypeDoc.Factories { + /** + * A handler that moves comments with dot syntax to their target. + */ + class DeepCommentHandler extends BaseHandler { + /** + * Create a new CommentHandler instance. + * + * @param dispatcher The dispatcher this handler should be attached to. + */ + constructor(dispatcher: Dispatcher); + /** + * Triggered when the dispatcher starts processing a declaration. + * + * @param state The state that describes the current declaration and reflection. + */ + private onDeclaration(state); + } +} declare module TypeDoc.Factories { /** * A handler that truncates the names of dynamic modules to not include the @@ -984,11 +1003,11 @@ declare module TypeDoc.Factories { */ constructor(dispatcher: Dispatcher); /** - * Triggered when the dispatcher processes a declaration. + * Triggered when the dispatcher has finished processing a declaration. * * @param state The state that describes the current declaration and reflection. */ - private onDeclaration(state); + private onEndDeclaration(state); } } declare module TypeDoc.Factories { @@ -1221,11 +1240,11 @@ declare module TypeDoc.Factories { */ constructor(dispatcher: Dispatcher); /** - * Triggered when the dispatcher starts processing a declaration. + * Triggered when the dispatcher has finished processing a declaration. * * @param state The state that describes the current declaration and reflection. */ - private onDeclaration(state); + private onEndDeclaration(state); static getLiteralDeclaration(declaration: TypeScript.PullDecl): TypeScript.PullDecl; } } @@ -1695,6 +1714,10 @@ declare module TypeDoc.Models { */ public name: string; /** + * The original name of the TypeScript declaration. + */ + public originalName: string; + /** * The parsed documentation comment attached to this reflection. */ public comment: Comment; diff --git a/bin/typedoc.js b/bin/typedoc.js index 6f4990d42..e5bb39dd8 100644 --- a/bin/typedoc.js +++ b/bin/typedoc.js @@ -1478,7 +1478,7 @@ var TypeDoc; var len = basePath.length; while (basePath != dirname.substr(0, len)) { - if (len <= dirname.length) { + if (len >= dirname.length) { return; } @@ -1926,6 +1926,7 @@ var TypeDoc; var parent = state.parentState.reflection; var reflection = new TypeDoc.Models.DeclarationReflection(); reflection.name = (state.flattenedName ? state.flattenedName + '.' : '') + state.getName(); + reflection.originalName = state.declaration.name; reflection.parent = parent; state.reflection = reflection; @@ -2572,6 +2573,74 @@ var TypeDoc; var Factories = TypeDoc.Factories; })(TypeDoc || (TypeDoc = {})); var TypeDoc; +(function (TypeDoc) { + (function (Factories) { + /** + * A handler that moves comments with dot syntax to their target. + */ + var DeepCommentHandler = (function (_super) { + __extends(DeepCommentHandler, _super); + /** + * Create a new CommentHandler instance. + * + * @param dispatcher The dispatcher this handler should be attached to. + */ + function DeepCommentHandler(dispatcher) { + _super.call(this, dispatcher); + + dispatcher.on(Factories.Dispatcher.EVENT_DECLARATION, this.onDeclaration, this, -512); + } + /** + * Triggered when the dispatcher starts processing a declaration. + * + * @param state The state that describes the current declaration and reflection. + */ + DeepCommentHandler.prototype.onDeclaration = function (state) { + var reflection = state.reflection; + if (reflection.comment) { + return; + } + + function push(reflection) { + var part = reflection.originalName; + if (reflection.isSignature) { + part = ''; + } + + if (part && part != '') { + name = (name == '' ? part : part + '.' + name); + } + } + + var name = ''; + var target = reflection.parent; + push(reflection); + + while (target instanceof TypeDoc.Models.DeclarationReflection) { + if (target.comment) { + var tag = target.comment.getTag('param', name); + if (tag) { + target.comment.tags.splice(target.comment.tags.indexOf(tag), 1); + reflection.comment = new TypeDoc.Models.Comment('', tag.text); + break; + } + } + + target = target.parent; + } + }; + return DeepCommentHandler; + })(Factories.BaseHandler); + Factories.DeepCommentHandler = DeepCommentHandler; + + /** + * Register this handler. + */ + Factories.Dispatcher.HANDLERS.push(DeepCommentHandler); + })(TypeDoc.Factories || (TypeDoc.Factories = {})); + var Factories = TypeDoc.Factories; +})(TypeDoc || (TypeDoc = {})); +var TypeDoc; (function (TypeDoc) { (function (Factories) { /** @@ -2931,14 +3000,14 @@ var TypeDoc; function FunctionTypeHandler(dispatcher) { _super.call(this, dispatcher); - dispatcher.on(Factories.Dispatcher.EVENT_DECLARATION, this.onDeclaration, this, -256); + dispatcher.on(Factories.Dispatcher.EVENT_END_DECLARATION, this.onEndDeclaration, this); } /** - * Triggered when the dispatcher processes a declaration. + * Triggered when the dispatcher has finished processing a declaration. * * @param state The state that describes the current declaration and reflection. */ - FunctionTypeHandler.prototype.onDeclaration = function (state) { + FunctionTypeHandler.prototype.onEndDeclaration = function (state) { if (state.isSignature) { return; } @@ -3578,14 +3647,14 @@ var TypeDoc; function ObjectLiteralHandler(dispatcher) { _super.call(this, dispatcher); - dispatcher.on(Factories.Dispatcher.EVENT_DECLARATION, this.onDeclaration, this, 1024); + dispatcher.on(Factories.Dispatcher.EVENT_END_DECLARATION, this.onEndDeclaration, this); } /** - * Triggered when the dispatcher starts processing a declaration. + * Triggered when the dispatcher has finished processing a declaration. * * @param state The state that describes the current declaration and reflection. */ - ObjectLiteralHandler.prototype.onDeclaration = function (state) { + ObjectLiteralHandler.prototype.onEndDeclaration = function (state) { var _this = this; var literal = ObjectLiteralHandler.getLiteralDeclaration(state.declaration); if (literal && literal.getChildDecls().length > 0) {