feat: Support for specifying comments on export declarations

Also soft-deprecates the use of `@packageDocumentation` to mark a comment as a module comment. Use `@module` instead.

Resolves #1504.

Author: Gerrit0

examples/basic/src/single-export.ts

@@ -46,7 +46,4 @@ class SingleExportedClass {
     }
 }
 
-/**
- * The export statement.
- */
 export = SingleExportedClass;

src/lib/converter/context.ts

@@ -70,6 +70,19 @@ export class Context {
         this.convertingTypeNode = true;
     }
 
+    /**
+     * This is a horrible hack to avoid breaking backwards compatibility for plugins
+     * that use EVENT_CREATE_DECLARATION. The comment plugin needs to be able to check
+     * this to properly get the comment for module re-exports:
+     * ```ts
+     * /** We should use this comment */
+     * export * as Mod from "./mod"
+     * ```
+     * Will be removed in 0.21.
+     * @internal
+     */
+    exportSymbol?: ts.Symbol;
+
     private convertingTypeNode = false;
 
     /**
@@ -169,22 +182,31 @@ export class Context {
     createDeclarationReflection(
         kind: ReflectionKind,
         symbol: ts.Symbol | undefined,
-        name = getHumanName(symbol?.name ?? "unknown")
+        exportSymbol: ts.Symbol | undefined,
+        // We need this because modules don't always have symbols.
+        nameOverride?: string
     ) {
+        const name = getHumanName(
+            nameOverride ?? exportSymbol?.name ?? symbol?.name ?? "unknown"
+        );
         const reflection = new DeclarationReflection(name, kind, this.scope);
         this.addChild(reflection);
         if (symbol && this.converter.isExternal(symbol)) {
             reflection.setFlag(ReflectionFlag.External);
         }
+        if (exportSymbol) {
+            this.registerReflection(reflection, exportSymbol);
+        }
         this.registerReflection(reflection, symbol);
 
+        this.exportSymbol = exportSymbol;
         this.converter.trigger(
             ConverterEvents.CREATE_DECLARATION,
             this,
             reflection,
-            // FIXME this isn't good enough.
             symbol && this.converter.getNodesForSymbol(symbol, kind)[0]
         );
+        this.exportSymbol = undefined;
 
         return reflection;
     }

src/lib/converter/converter.ts

@@ -320,6 +320,7 @@ export class Converter extends ChildableComponent<
             const reflection = context.createDeclarationReflection(
                 ReflectionKind.Module,
                 symbol,
+                void 0,
                 entryName
             );
             moduleContext = context.withScope(reflection);

src/lib/converter/factories/comment.ts

@@ -119,13 +119,26 @@ export function getRawComment(node: ts.Node): string | undefined {
         } else {
             node = getRootModuleDeclaration(<ts.ModuleDeclaration>node);
         }
+    } else if (node.kind === ts.SyntaxKind.NamespaceExport) {
+        node = node.parent;
+    } else if (node.kind === ts.SyntaxKind.ExportSpecifier) {
+        node = node.parent.parent;
     }
 
     const sourceFile = node.getSourceFile();
     const comments = getJSDocCommentRanges(node, sourceFile.text);
     if (comments.length) {
         let comment: ts.CommentRange;
-        const explicitPackageComment = comments.find((comment) =>
+        let explicitPackageComment = comments.find((comment) =>
+            sourceFile.text
+                .substring(comment.pos, comment.end)
+                .includes("@module")
+        );
+
+        // TODO: Deprecate and remove. This is an abuse of the @packageDocumentation tag. See:
+        // https://github.com/TypeStrong/typedoc/issues/1504#issuecomment-775842609
+        // Deprecate in 0.21, remove in 0.22
+        explicitPackageComment ??= comments.find((comment) =>
             sourceFile.text
                 .substring(comment.pos, comment.end)
                 .includes("@packageDocumentation")
@@ -138,20 +151,33 @@ export function getRawComment(node: ts.Node): string | undefined {
                 // FUTURE: GH#1083, follow deprecation process to phase this out.
                 comment = comments[0];
             } else {
-                // Single comment that may be a license comment, bail.
+                // Single comment that may be a license comment, or no comments, bail.
                 return;
             }
         } else {
             comment = comments[comments.length - 1];
             // If a non-SourceFile node comment has this tag, it should not be attached to the node
             // as it documents the whole file by convention.
+            // TODO: Deprecate and remove. This is an abuse of the @packageDocumentation tag. See:
+            // https://github.com/TypeStrong/typedoc/issues/1504#issuecomment-775842609
+            // Deprecate in 0.21, remove in 0.22
             if (
                 sourceFile.text
                     .substring(comment.pos, comment.end)
                     .includes("@packageDocumentation")
             ) {
                 return;
             }
+
+            // If a non-SourceFile node comment has this tag, it should not be attached to the node
+            // as it documents the module.
+            if (
+                sourceFile.text
+                    .substring(comment.pos, comment.end)
+                    .includes("@module")
+            ) {
+                return;
+            }
         }
 
         return sourceFile.text.substring(comment.pos, comment.end);
@@ -164,8 +190,8 @@ export function getRawComment(node: ts.Node): string | undefined {
  * Parse the given doc comment string.
  *
  * @param text     The doc comment string that should be parsed.
- * @param comment  The [[Models.Comment]] instance the parsed results should be stored into.
- * @returns        A populated [[Models.Comment]] instance.
+ * @param comment  The {@link Comment} instance the parsed results should be stored into.
+ * @returns        A populated {@link Comment} instance.
  */
 export function parseComment(
     text: string,

src/lib/converter/jsdoc.ts

@@ -23,20 +23,20 @@ export function convertJsDocAlias(
     context: Context,
     symbol: ts.Symbol,
     declaration: ts.JSDocTypedefTag | ts.JSDocEnumTag,
-    nameOverride?: string
+    exportSymbol?: ts.Symbol
 ) {
     if (
         declaration.typeExpression &&
         ts.isJSDocTypeLiteral(declaration.typeExpression)
     ) {
-        convertJsDocInterface(context, declaration, symbol, nameOverride);
+        convertJsDocInterface(context, declaration, symbol, exportSymbol);
         return;
     }
 
     const reflection = context.createDeclarationReflection(
         ReflectionKind.TypeAlias,
         symbol,
-        nameOverride
+        exportSymbol
     );
 
     reflection.type = context.converter.convertType(
@@ -54,12 +54,12 @@ export function convertJsDocCallback(
     context: Context,
     symbol: ts.Symbol,
     declaration: ts.JSDocCallbackTag,
-    nameOverride?: string
+    exportSymbol?: ts.Symbol
 ) {
     const alias = context.createDeclarationReflection(
         ReflectionKind.TypeAlias,
         symbol,
-        nameOverride
+        exportSymbol
     );
     const ac = context.withScope(alias);
 
@@ -71,12 +71,12 @@ function convertJsDocInterface(
     context: Context,
     declaration: ts.JSDocTypedefTag | ts.JSDocEnumTag,
     symbol: ts.Symbol,
-    nameOverride?: string
+    exportSymbol?: ts.Symbol
 ) {
     const reflection = context.createDeclarationReflection(
         ReflectionKind.Interface,
         symbol,
-        nameOverride
+        exportSymbol
     );
     const rc = context.withScope(reflection);
 

src/lib/converter/plugins/CommentPlugin.ts

@@ -107,6 +107,7 @@ export class CommentPlugin extends ConverterComponent {
             ) ||
             reflection.kind === ReflectionKind.Project
         ) {
+            comment.removeTags("module");
             comment.removeTags("packagedocumentation");
         }
     }
@@ -158,33 +159,40 @@ export class CommentPlugin extends ConverterComponent {
      * @param node  The node that is currently processed if available.
      */
     private onDeclaration(
-        _context: Context,
+        context: Context,
         reflection: Reflection,
         node?: ts.Node
     ) {
-        if (!node) {
-            return;
-        }
         if (reflection.kindOf(ReflectionKind.FunctionOrMethod)) {
             return;
         }
-        const rawComment = getRawComment(node);
+
+        // Clean this up in 0.21. We should really accept a ts.Symbol so we don't need exportSymbol on Context
+        const exportNode = context.exportSymbol?.getDeclarations()?.[0];
+        let rawComment = exportNode && getRawComment(exportNode);
+        rawComment ??= node && getRawComment(node);
         if (!rawComment) {
             return;
         }
 
         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");
+            const tag = comment.getTag("module");
             if (tag) {
-                reflection.name = tag.text.trim();
-                removeIfPresent(reflection.comment?.tags, tag);
+                // If no name is specified, this is a flag to mark a comment as a module comment
+                // and should not result in a reflection rename.
+                const newName = tag.text.trim();
+                if (newName.length) {
+                    reflection.name = newName;
+                }
+                removeIfPresent(comment.tags, tag);
             }
         }
+
+        this.applyModifiers(reflection, comment);
+        this.removeExcludedTags(comment);
+        reflection.comment = comment;
     }
 
     /**