fix: Comments on projects were broken

Author: Gerrit0

src/lib/converter/converter.ts

@@ -310,6 +310,11 @@ export class Converter extends ChildableComponent<
             // Special case for when we're giving a single entry point, we don't need to
             // create modules for each entry. Register the project as this module.
             context.project.registerReflection(context.project, symbol);
+            context.trigger(
+                Converter.EVENT_CREATE_DECLARATION,
+                context.project,
+                node
+            );
             moduleContext = context;
         } else {
             const reflection = context.createDeclarationReflection(

src/lib/converter/plugins/CommentPlugin.ts

@@ -38,26 +38,6 @@ const TAG_BLACKLIST = [
     "typedef",
 ];
 
-/**
- * Structure used by [[ContainerCommentHandler]] to store discovered module comments.
- */
-interface ModuleComment {
-    /**
-     * The module reflection this comment is targeting.
-     */
-    reflection: Reflection;
-
-    /**
-     * The full text of the best matched comment.
-     */
-    fullText: string;
-
-    /**
-     * Has the full text been marked as being preferred?
-     */
-    isPreferred: boolean;
-}
-
 /**
  * A handler that parses TypeDoc comments and attaches [[Comment]] instances to
  * the generated reflections.
@@ -67,18 +47,11 @@ export class CommentPlugin extends ConverterComponent {
     @BindOption("excludeTags")
     excludeTags!: string[];
 
-    /**
-     * List of discovered module comments.
-     * Defined in this.onBegin
-     */
-    private comments!: { [id: number]: ModuleComment };
-
     /**
      * Create a new CommentPlugin instance.
      */
     initialize() {
         this.listenTo(this.owner, {
-            [Converter.EVENT_BEGIN]: this.onBegin,
             [Converter.EVENT_CREATE_DECLARATION]: this.onDeclaration,
             [Converter.EVENT_CREATE_SIGNATURE]: this.onDeclaration,
             [Converter.EVENT_CREATE_TYPE_PARAMETER]: this.onCreateTypeParameter,
@@ -87,29 +60,6 @@ export class CommentPlugin extends ConverterComponent {
         });
     }
 
-    private storeModuleComment(comment: string, reflection: Reflection) {
-        const isPreferred = comment.toLowerCase().includes("@preferred");
-
-        if (this.comments[reflection.id]) {
-            const info = this.comments[reflection.id];
-            if (
-                !isPreferred &&
-                (info.isPreferred || info.fullText.length > comment.length)
-            ) {
-                return;
-            }
-
-            info.fullText = comment;
-            info.isPreferred = isPreferred;
-        } else {
-            this.comments[reflection.id] = {
-                reflection: reflection,
-                fullText: comment,
-                isPreferred: isPreferred,
-            };
-        }
-    }
-
     /**
      * Apply all comment tag modifiers to the given reflection.
      *
@@ -152,19 +102,15 @@ export class CommentPlugin extends ConverterComponent {
         }
 
         if (
-            reflection.kindOf(ReflectionKind.Module | ReflectionKind.Namespace)
+            reflection.kindOf(
+                ReflectionKind.Module | ReflectionKind.Namespace
+            ) ||
+            reflection.kind === ReflectionKind.Project
         ) {
             comment.removeTags("packagedocumentation");
         }
     }
 
-    /**
-     * Triggered when the converter begins converting a project.
-     */
-    private onBegin(_context: Context) {
-        this.comments = {};
-    }
-
     /**
      * Triggered when the converter has created a type parameter reflection.
      *
@@ -227,14 +173,10 @@ export class CommentPlugin extends ConverterComponent {
             return;
         }
 
-        if (reflection.kindOf(ReflectionKind.Namespace)) {
-            this.storeModuleComment(rawComment, reflection);
-        } else {
-            const comment = parseComment(rawComment, reflection.comment);
-            this.applyModifiers(reflection, comment);
-            this.removeExcludedTags(comment);
-            reflection.comment = comment;
-        }
+        const comment = parseComment(rawComment, reflection.comment);
+        this.applyModifiers(reflection, comment);
+        this.removeExcludedTags(comment);
+        reflection.comment = comment;
 
         if (reflection.kindOf(ReflectionKind.Module)) {
             const tag = reflection.comment?.getTag("module");
@@ -251,14 +193,6 @@ export class CommentPlugin extends ConverterComponent {
      * @param context  The context object describing the current state the converter is in.
      */
     private onBeginResolve(context: Context) {
-        for (const info of Object.values(this.comments)) {
-            const comment = parseComment(info.fullText);
-            comment.removeTags("preferred");
-
-            this.applyModifiers(info.reflection, comment);
-            info.reflection.comment = comment;
-        }
-
         const excludeInternal = this.application.options.getValue(
             "excludeInternal"
         );

src/test/converter/js/index.js

@@ -1,3 +1,5 @@
+/** */
+
 /**
  * not included anywhere
  * @typedef {Object} InterfaceIsh

src/test/converter/js/specs.json

@@ -4,6 +4,7 @@
   "kind": 0,
   "kindString": "Project",
   "flags": {},
+  "comment": {},
   "children": [
     {
       "id": 11,