Added DeepCommentHandler

Author: sebastian-lenz

examples/basic/src/flattened.ts

@@ -6,10 +6,10 @@ class flattenedClass
     /**
      * A member that accepts an option object defined inline.
      *
-     * @param value                   A value on the options object parameter.
-     * @param anotherValue            Another value on the options object parameter.
-     * @param moreOptions             A typed child object of the options object.
-     * @param moreOptions.moreValues  A value of the typed child object.
+     * @param options.value                   A value on the options object parameter.
+     * @param options.anotherValue            Another value on the options object parameter.
+     * @param options.moreOptions             A typed child object of the options object.
+     * @param options.moreOptions.moreValues  A value of the typed child object.
      */
     options:{
         value?:string;
@@ -22,15 +22,16 @@ class flattenedClass
     /**
      * A member that holds a callback that requires a typed function signature.
      *
-     * @param param          A parameter of the typed function callback.
-     * @param optionalParam  An optional parameter of the typed function callback.
+     * @param callback.param          A parameter of the typed function callback.
+     * @param callback.optionalParam  An optional parameter of the typed function callback.
      */
     callback:(param:number, optionalParam?:string) => string;
 
     /**
      * A member that holds an index signature.
      *
-     * @param text  A property of the index signature instance.
+     * @param indexed.index  The index property comment.
+     * @param indexed.test   A property of the index signature instance.
      */
     indexed:{
         [index:number]:{name:string; value?:number;};
@@ -47,7 +48,7 @@ class flattenedClass
      * @param options.moreOptions             A typed child object of the options object.
      * @param options.moreOptions.moreValues  A value of the typed child object.
      */
-    construct(options:{
+    constructor(options:{
         value?:string;
         anotherValue?:string;
         moreOptions?:{
@@ -88,8 +89,9 @@ function flattenedObject(options:{
 /**
  * A function that accepts an index signature parameter.
  *
- * @param indexed       The index signature parameter.
- * @param indexed.text  A property of the index signature instance.
+ * @param indexed        The index signature parameter.
+ * @param indexed.index  The index property comment.
+ * @param indexed.test   A property of the index signature instance.
  */
 function flattenedIndexSignature(indexed:{
     [index:number]:{name:string; value?:number;};

examples/basic/src/functions.ts

@@ -62,7 +62,8 @@ export function multipleSignatures(value:string):string;
 /**
  * This is the second signature a function with multiple signatures.
  *
- * @param value  An object containing the name value.
+ * @param value       An object containing the name value.
+ * @param value.name  A value of the object.
  */
 export function multipleSignatures(value:{name:string}):string;
 
@@ -93,8 +94,10 @@ export function genericFunction<T>(value:T):T {
 
 /**
  * This is a function that is extended by a module.
+ *
+ * @param arg An argument.
  */
-export function moduleFunction() { }
+export function moduleFunction(arg:string):string { return ''; }
 
 
 /**

src/typedoc/factories/Dispatcher.ts

@@ -285,6 +285,7 @@ module TypeDoc.Factories
             var parent        = <Models.DeclarationReflection>state.parentState.reflection;
             var reflection    = new Models.DeclarationReflection();
             reflection.name   = (state.flattenedName ? state.flattenedName + '.' : '') + state.getName();
+            reflection.originalName = state.declaration.name;
             reflection.parent = parent;
 
             state.reflection = reflection;

src/typedoc/factories/handlers/DeepCommentHandler.ts

@@ -0,0 +1,66 @@
+module TypeDoc.Factories
+{
+    /**
+     * A handler that moves comments with dot syntax to their target.
+     */
+    export class DeepCommentHandler extends BaseHandler
+    {
+        /**
+         * Create a new CommentHandler instance.
+         *
+         * @param dispatcher  The dispatcher this handler should be attached to.
+         */
+        constructor(dispatcher:Dispatcher) {
+            super(dispatcher);
+
+            dispatcher.on(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.
+         */
+        private onDeclaration(state:DeclarationState) {
+            var reflection = state.reflection;
+            if (reflection.comment) {
+                return;
+            }
+
+            function push(reflection:Models.DeclarationReflection) {
+                var part = reflection.originalName;
+                if (reflection.isSignature) {
+                    part = '';
+                }
+
+                if (part && part != '') {
+                    name = (name == '' ? part : part + '.' + name);
+                }
+            }
+
+            var name   = '';
+            var target = <Models.DeclarationReflection>reflection.parent;
+            push(reflection);
+
+            while (target instanceof 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 Models.Comment('', tag.text);
+                        break;
+                    }
+                }
+
+                target = <Models.DeclarationReflection>target.parent;
+            }
+        }
+    }
+
+
+    /**
+     * Register this handler.
+     */
+    Dispatcher.HANDLERS.push(DeepCommentHandler);
+}

src/typedoc/factories/handlers/FunctionTypeHandler.ts

@@ -13,16 +13,16 @@ module TypeDoc.Factories
         constructor(dispatcher:Dispatcher) {
             super(dispatcher);
 
-            dispatcher.on(Dispatcher.EVENT_DECLARATION, this.onDeclaration, this, -256);
+            dispatcher.on(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.
          */
-        private onDeclaration(state:DeclarationState) {
+        private onEndDeclaration(state:DeclarationState) {
             if (state.isSignature) {
                 return;
             }

src/typedoc/factories/handlers/ObjectLiteralHandler.ts

@@ -13,16 +13,16 @@ module TypeDoc.Factories
         constructor(dispatcher:Dispatcher) {
             super(dispatcher);
 
-            dispatcher.on(Dispatcher.EVENT_DECLARATION, this.onDeclaration, this, 1024);
+            dispatcher.on(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.
          */
-        private onDeclaration(state:DeclarationState) {
+        private onEndDeclaration(state:DeclarationState) {
             var literal = ObjectLiteralHandler.getLiteralDeclaration(state.declaration);
             if (literal && literal.getChildDecls().length > 0) {
                 if (state.kindOf(TypeScript.PullElementKind.Variable)) {

src/typedoc/models/reflections/BaseReflection.ts

@@ -55,6 +55,11 @@ module TypeDoc.Models
          */
         name:string = '';
 
+        /**
+         * The original name of the TypeScript declaration.
+         */
+        originalName:string;
+
         /**
          * The parsed documentation comment attached to this reflection.
          */