Add @alias tag, fixes #3096

This probably isn't the name I'll end up using as it conflicts badly
with JSDoc's `@alias` tag.... `@reExport`?

Author: Gerrit0

site/tags.md

@@ -2,6 +2,7 @@
 title: Tags
 children:
     - tags/abstract.md
+    - tags/alias.md
     - tags/alpha.md
     - tags/author.md
     - tags/beta.md
@@ -195,6 +196,7 @@ export type Foo = { a: string };
 ```
 
 - [`@abstract`](./tags/abstract.md)
+- [`@alias`](./tags/alias.md)
 - [`@alpha`](./tags/alpha.md)
 - [`@beta`](./tags/beta.md)
 - [`@class`](./tags/class.md)

site/tags/alias.md

@@ -0,0 +1,47 @@
+---
+title: "@alias"
+---
+
+# @alias
+
+**Tag Kind:** [Modifier](../tags.md#modifier-tags)
+
+The `@alias` tag is valid on type alias and variable declarations which directly reference another
+symbol. When present, it instructs TypeDoc that the variable it is present on should be treated as
+if it was a re-export of the referenced symbol rather than being converted directly.
+
+> [!note]
+> It should generally be preferred to use real re-exports to construct your public API instead
+> of introducing new symbols with type aliases or variables. Using real re-exports will result
+> in a better developer experience for consumers of your library using Go To Definition to navigate
+> within your library.
+
+
+## Example
+
+Assuming that `Vector` in `utils.js` is declared as a class, this will cause TypeDoc to convert
+the `Math` namespace as if the `Vector` class was declared directly within the namespace rather than
+being imported from another file. Similarly, the `IsInt` type alias will be treated as a re-export.
+
+```ts
+import { Vector as _Vector, IsInt as _IsInt } from "./utils.js"
+
+export namespace Math {
+    /** @alias */
+    export const Vector = _Vector;
+    export type Vector = typeof _Vector;
+
+    /** @alias */
+    export type IsInt<T extends number> = _IsInt<T>;
+
+    // The following are all invalid usage of the @alias tag and will produce a warning
+    /** @alias */
+    export type BadAlias1 = 123;
+    /** @alias */
+    export const BadAlias2 = { someImportedFunction };
+}
+```
+
+## See Also
+
+- The [`@inline`](inline.md) tag

src/lib/application.ts

@@ -690,7 +690,7 @@ export class Application extends AbstractComponent<
         const start = Date.now();
 
         // No point in validating exports when merging. Warnings will have already been emitted when
-        // creating the project jsons that this run merges together.
+        // creating the project JSONs that this run merges together.
         if (
             checks.notExported &&
             this.entryPointStrategy !== EntryPointStrategy.Merge

src/lib/converter/symbols.ts

@@ -349,11 +349,29 @@ function convertTypeAlias(
     assert(declaration);
 
     if (ts.isTypeAliasDeclaration(declaration)) {
-        if (
-            context
-                .getComment(symbol, ReflectionKind.TypeAlias)
-                ?.hasModifier("@interface")
-        ) {
+        const comment = context.getComment(symbol, ReflectionKind.TypeAlias);
+
+        if (comment?.hasModifier("@alias")) {
+            if (ts.isTypeReferenceNode(declaration.type)) {
+                // Note: Get the symbol from the typeName here, NOT the type! The type refers to this alias,
+                // not the type alias we want to convert.
+                const type = context.getTypeAtLocation(declaration.type.typeName);
+                const aliasedSymbol = type?.aliasSymbol ?? type?.getSymbol() ?? declaration.type.typeName.symbol;
+                if (aliasedSymbol) {
+                    convertSymbol(context, aliasedSymbol, exportSymbol || symbol);
+                    return;
+                } else {
+                    context.logger.warn(
+                        i18n.failed_to_convert_0_as_alias(exportSymbol?.name ?? symbol.name),
+                        declaration,
+                    );
+                }
+            } else {
+                context.logger.warn(i18n.failed_to_convert_0_as_alias(exportSymbol?.name ?? symbol.name), declaration);
+            }
+        }
+
+        if (comment?.hasModifier("@interface")) {
             return convertTypeAliasAsInterface(
                 context,
                 symbol,
@@ -1005,6 +1023,19 @@ function convertVariable(
         ? context.checker.getTypeOfSymbolAtLocation(symbol, declaration)
         : context.checker.getTypeOfSymbol(symbol);
 
+    if (comment?.hasModifier("@alias")) {
+        if (
+            declaration && ts.isVariableDeclaration(declaration) && declaration.initializer &&
+            (ts.isIdentifier(declaration.initializer) || ts.isPropertyAccessExpression(declaration.initializer))
+        ) {
+            const aliasedSymbol = context.expectSymbolAtLocation(declaration.initializer);
+            convertSymbol(context, aliasedSymbol, exportSymbol || symbol);
+            return ts.SymbolFlags.Property | ts.SymbolFlags.ValueModule | ts.SymbolFlags.TypeAlias;
+        } else {
+            context.logger.warn(i18n.failed_to_convert_0_as_alias(exportSymbol?.name ?? symbol.name), declaration);
+        }
+    }
+
     if (
         isEnumLike(context.checker, type, declaration) &&
         comment?.hasModifier("@enum")

src/lib/internationalization/locales/en.cts

@@ -53,6 +53,7 @@ export = {
         `{0} is being converted as a class, but does not have any construct signatures`,
     converting_0_as_enum_requires_value_declaration:
         `Converting {0} as an enum requires a declaration which represents a non-type value`,
+    failed_to_convert_0_as_alias: "Failed to convert {0} as an alias because it is not direct reference.",
 
     comment_for_0_should_not_contain_block_or_modifier_tags:
         `The comment for {0} should not contain any block or modifier tags`,

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

@@ -75,6 +75,7 @@ export const tsdocModifierTags = [
 export const modifierTags = [
     ...tsdocModifierTags,
     "@abstract",
+    "@alias",
     "@class",
     "@disableGroups",
     "@enum",

src/test/behavior.c2.test.ts

@@ -2,7 +2,6 @@ import { deepStrictEqual as equal, ok } from "assert";
 import {
     Comment,
     CommentTag,
-    type ContainerReflection,
     LiteralType,
     Reflection,
     ReflectionKind,
@@ -14,20 +13,6 @@ import { TestLogger } from "./TestLogger.js";
 import { getComment, getSigComment, query, querySig, reflToTree } from "./utils.js";
 import { getConverter2App, getConverter2Project } from "./programs.js";
 
-type NameTree = { [name: string]: NameTree | undefined };
-
-function buildNameTree(
-    refl: ContainerReflection,
-    tree: NameTree = {},
-): NameTree {
-    for (const child of refl.children || []) {
-        tree[child.name] ||= {};
-        buildNameTree(child, tree[child.name]);
-    }
-
-    return tree;
-}
-
 function getLinks(refl: Reflection) {
     ok(refl.comment);
     return filterMap(refl.comment.summary, (p) => {
@@ -419,11 +404,11 @@ describe("Behavior Tests", () => {
         app.options.setValue("excludeNotDocumented", true);
         app.options.setValue("excludeNotDocumentedKinds", ["Property"]);
         const project = convert("excludeNotDocumentedKinds");
-        equal(buildNameTree(project), {
+        equal(reflToTree(project), {
             NotDoc: {
-                prop: {},
+                prop: "Property",
             },
-            identity: {},
+            identity: "Function",
         });
     });
 
@@ -1526,4 +1511,25 @@ describe("Behavior Tests", () => {
         // Inherits description from class's @template
         equal(Comment.combineDisplayParts(ctor.signatures[1].typeParameters?.[0].comment?.summary), "class docs");
     });
+
+    it("Supports the @alias tag", () => {
+        const project = convert("alias");
+
+        logger.expectMessage("warn: Failed to convert BadAlias as an alias because it is not direct reference.");
+
+        equal(reflToTree(project), {
+            Math: {
+                BadAlias: "TypeAlias",
+                IsInt: "TypeAlias",
+                Vec: {
+                    "Constructor:constructor": "Constructor",
+                    mag: "Method",
+                },
+                makeVec: "Function",
+            },
+        });
+
+        const bad = query(project, "Math.BadAlias");
+        equal(bad.comment?.modifierTags, new Set(["@alias"]));
+    });
 });

src/test/converter2/behavior/alias.ts

@@ -0,0 +1,27 @@
+/** Class comment */
+class _Vec {
+    mag() {}
+}
+
+/** Type comment */
+type _IsInt<T extends number> = `${T}` extends `${bigint}` ? true : false;
+
+/** Func comment */
+function _makeVec(x: number, y: number, z: number): _Vec {
+    return new _Vec();
+}
+
+export namespace Math {
+    // /** Alias comment @alias */
+    export type IsInt<T extends number> = _IsInt<T>;
+
+    /** Alias comment @alias */
+    export const Vec = _Vec;
+    export type Vec = typeof _Vec;
+
+    /** Alias comment @alias */
+    export const makeVec = _makeVec;
+
+    /** @alias */
+    export type BadAlias = 123;
+}

tsdoc.json

@@ -80,6 +80,10 @@
             "tagName": "@abstract",
             "syntaxKind": "modifier"
         },
+        {
+            "tagName": "@alias",
+            "syntaxKind": "modifier"
+        },
         {
             "tagName": "@document",
             "syntaxKind": "block"