Add support for @namespace tag

Closes #2055

Author: Gerrit0

CHANGELOG.md

@@ -46,6 +46,7 @@
 -   TypeDoc options may now be set under the `typedocOptions` key in `package.json`, #2112.
 -   Moved sidebar to left of content for consistency with most other websites, #2189.
 -   Added `--cacheBust` option to tell TypeDoc to include include the generation time in files, #2124.
+-   Added support for `@namespace` on variable declarations to tell TypeDoc to convert the variable as a namespace, #2055.
 
 ### Bug Fixes
 

src/lib/converter/comments/discovery.ts

@@ -5,6 +5,20 @@ import { CommentStyle } from "../../utils/options/declaration";
 import { nicePath } from "../../utils/paths";
 import { ok } from "assert";
 
+const variablePropertyKinds = [
+    ts.SyntaxKind.PropertyDeclaration,
+    ts.SyntaxKind.PropertySignature,
+    ts.SyntaxKind.BinaryExpression,
+    ts.SyntaxKind.PropertyAssignment,
+    // class X { constructor(/** Comment */ readonly z: string) }
+    ts.SyntaxKind.Parameter,
+    // Variable values
+    ts.SyntaxKind.VariableDeclaration,
+    ts.SyntaxKind.BindingElement,
+    ts.SyntaxKind.ExportAssignment,
+    ts.SyntaxKind.PropertyAccessExpression,
+];
+
 // Note: This does NOT include JSDoc syntax kinds. This is important!
 // Comments from @typedef and @callback tags are handled specially by
 // the JSDoc converter because we only want part of the comment when
@@ -18,6 +32,11 @@ const wantedKinds: Record<ReflectionKind, ts.SyntaxKind[]> = {
         ts.SyntaxKind.BindingElement,
         ts.SyntaxKind.ExportSpecifier,
         ts.SyntaxKind.NamespaceExport,
+        // @namespace support
+        ts.SyntaxKind.VariableDeclaration,
+        ts.SyntaxKind.BindingElement,
+        ts.SyntaxKind.ExportAssignment,
+        ts.SyntaxKind.PropertyAccessExpression,
     ],
     [ReflectionKind.Enum]: [
         ts.SyntaxKind.EnumDeclaration,
@@ -29,13 +48,7 @@ const wantedKinds: Record<ReflectionKind, ts.SyntaxKind[]> = {
         ts.SyntaxKind.PropertyAssignment,
         ts.SyntaxKind.PropertySignature,
     ],
-    [ReflectionKind.Variable]: [
-        // everything here should also be in ReflectionKind.Property
-        ts.SyntaxKind.VariableDeclaration,
-        ts.SyntaxKind.BindingElement,
-        ts.SyntaxKind.ExportAssignment,
-        ts.SyntaxKind.PropertyAccessExpression,
-    ],
+    [ReflectionKind.Variable]: variablePropertyKinds,
     [ReflectionKind.Function]: [
         ts.SyntaxKind.FunctionDeclaration,
         ts.SyntaxKind.BindingElement,
@@ -49,19 +62,7 @@ const wantedKinds: Record<ReflectionKind, ts.SyntaxKind[]> = {
     ],
     [ReflectionKind.Interface]: [ts.SyntaxKind.InterfaceDeclaration],
     [ReflectionKind.Constructor]: [ts.SyntaxKind.Constructor],
-    [ReflectionKind.Property]: [
-        ts.SyntaxKind.PropertyDeclaration,
-        ts.SyntaxKind.PropertySignature,
-        ts.SyntaxKind.BinaryExpression,
-        ts.SyntaxKind.PropertyAssignment,
-        // class X { constructor(/** Comment */ readonly z: string) }
-        ts.SyntaxKind.Parameter,
-        // Variable values
-        ts.SyntaxKind.VariableDeclaration,
-        ts.SyntaxKind.BindingElement,
-        ts.SyntaxKind.ExportAssignment,
-        ts.SyntaxKind.PropertyAccessExpression,
-    ],
+    [ReflectionKind.Property]: variablePropertyKinds,
     [ReflectionKind.Method]: [
         ts.SyntaxKind.FunctionDeclaration,
         ts.SyntaxKind.MethodDeclaration,

src/lib/converter/plugins/CommentPlugin.ts

@@ -149,6 +149,10 @@ export class CommentPlugin extends ConverterComponent {
      * @param comment  The comment that should be searched for modifiers.
      */
     private applyModifiers(reflection: Reflection, comment: Comment) {
+        if (reflection.kindOf(ReflectionKind.SomeModule)) {
+            comment.removeModifier("@namespace");
+        }
+
         if (comment.hasModifier("@private")) {
             reflection.setFlag(ReflectionFlag.Private);
             if (reflection.kindOf(ReflectionKind.CallSignature)) {

src/lib/converter/symbols.ts

@@ -791,6 +791,10 @@ function convertVariable(
         return convertVariableAsEnum(context, symbol, exportSymbol);
     }
 
+    if (symbol.getJsDocTags().some((tag) => tag.name === "namespace")) {
+        return convertVariableAsNamespace(context, symbol, exportSymbol);
+    }
+
     if (type.getCallSignatures().length) {
         return convertVariableAsFunction(context, symbol, exportSymbol);
     }
@@ -876,6 +880,27 @@ function convertVariableAsEnum(
     return ts.SymbolFlags.TypeAlias;
 }
 
+function convertVariableAsNamespace(
+    context: Context,
+    symbol: ts.Symbol,
+    exportSymbol?: ts.Symbol
+) {
+    const reflection = context.createDeclarationReflection(
+        ReflectionKind.Namespace,
+        symbol,
+        exportSymbol
+    );
+    context.finalizeDeclarationReflection(reflection);
+    const rc = context.withScope(reflection);
+
+    const declaration = symbol.declarations![0] as ts.VariableDeclaration;
+    const type = context.checker.getTypeAtLocation(declaration);
+
+    convertSymbols(rc, type.getProperties());
+
+    return ts.SymbolFlags.Property;
+}
+
 function convertVariableAsFunction(
     context: Context,
     symbol: ts.Symbol,

src/lib/utils/options/tsdoc-defaults.ts

@@ -54,4 +54,5 @@ export const modifierTags = [
     "@enum",
     "@event",
     "@overload",
+    "@namespace",
 ] as const;

src/test/behaviorTests.ts

@@ -141,6 +141,21 @@ export const behaviorTests: {
         );
     },
 
+    constNamespace(project) {
+        const someNs = query(project, "someNs");
+        equal(someNs.kind, ReflectionKind.Namespace);
+        equal(Comment.combineDisplayParts(someNs.comment?.summary), "ns doc");
+
+        const a = query(project, "someNs.a");
+        equal(Comment.combineDisplayParts(a.comment?.summary), "a doc");
+
+        const b = query(project, "someNs.b");
+        equal(
+            Comment.combineDisplayParts(b.signatures?.[0].comment?.summary),
+            "b doc"
+        );
+    },
+
     constTypeParam(project) {
         const getNamesExactly = query(project, "getNamesExactly");
         const typeParams = getNamesExactly.signatures?.[0].typeParameters;

src/test/converter2/behavior/constNamespace.ts

@@ -0,0 +1,18 @@
+/**
+ * const doc
+ */
+export const someConst = {
+    /** a doc */
+    a: 123,
+
+    /** b doc */
+    b() {
+        return "456";
+    },
+};
+
+/**
+ * ns doc
+ * @namespace
+ */
+export const someNs = someConst;

src/test/issueTests.ts

@@ -325,7 +325,7 @@ export const issueTests: {
             project.children[1].signatures![0].comment?.summary,
         ].map(Comment.combineDisplayParts);
 
-        equal(comments, ["", "metadata", "fn", "bar"]);
+        equal(comments, ["bar", "metadata", "fn", "bar"]);
     },
 
     gh1660(project) {

tsdoc.json

@@ -82,6 +82,10 @@
         {
             "tagName": "@overload",
             "syntaxKind": "modifier"
+        },
+        {
+            "tagName": "@namespace",
+            "syntaxKind": "modifier"
         }
     ]
 }