Support inlining renamed type aliases in namespaces

[XeroAlpha]

Search Terms

inline type alias, replace type, namespace re-export

Problem

When organizing a library's public API using namespaces to re-export types from internal modules (often with renaming), Typedoc treats these as distinct type aliases. This triggers the referenced by ... but not included in the documentation warning for the original source types, cluttering the logs.

Currently, there is no clean way to tell Typedoc: "Treat this alias in the namespace exactly as if it were the original type definition."

Example Scenario:

1. Source (util.ts):

   export interface Vec { x: number; y: number; }
   export class Vector { /* ... */ }

2. Public API (index.ts):

   import { Vec as _Vec, Vector as _Vector } from './util.ts';
   
   export namespace Math {
       // I want Math.Vec to be treated exactly as the Vec interface
       export type Vec = _Vec; 
       
       // I want Math.Vector to be treated exactly as the Vector class
       export type Vector = _Vector;
       export const Vector = _Vector;
   }

Current Behavior:
Typedoc generates Math.Vec as a type alias pointing to Vec and emits a warning:

[warning] Vec, defined in util.ts, is referenced by Math.Vec but not included in the documentation.

Attempted Workarounds:

1. Tags: I have tried using @expand, @expandType, @inline, and @inlineType. None of these effectively replace the alias with the target definition in the generated documentation structure.
2. Syntax: export import Vec = _Vec; is invalid for types and values in this context (only supports namespaces).

Suggested Solution

I would like to request a feature (either a specific JSDoc tag or a configuration option) that allows replacing the alias/constant with the target definition.

[Gerrit0]

Is there a reason you are using namespaces instead of modules to do this structuring? Using modules has the benefit of playing much more nicely with editor tooling (go to definition) where it will follow through the alias to the original definition rather than requiring intermediate steps. Using modules also makes it easier for future developers to more quickly gain an intuition of where to go to find the definition rather than having to search each time.

//  math.ts -- honestly I'd probably put Vec and Vector here...
export { Vec, Vector } from "./util.ts"
// index.ts
export * as Math from "./math.ts"

With namespaces, these are not aliases according to the compiler, and while TypeDoc could probably do something hacky to try to make this work, it would likely be fragile, especially as soon as generics are involved.

[XeroAlpha]

Is there a reason you are using namespaces instead of modules to do this structuring?

Because I need a namespace to share the same name as a class. My use case is similar to this:

export class JLink {
    // ...
}

export namespace JLink {
    export class CPU {
        // ...
    }
    
    export class Memory {
        // ...
    }

    export interface DeviceInfo {
        // ...
    } 
}

I believe the best approach currently would be to allow the export import = syntax to directly reference non-namespace definitions.

TypeScript's checker.ts has this check:

// This function is only for imports with entity names
function getSymbolOfPartOfRightHandSideOfImportEquals(entityName: EntityName, dontResolveAlias?: boolean): Symbol | undefined {
    // There are three things we might try to look for. In the following examples,
    // the search term is enclosed in |...|:
    //
    //     import a = |b|; // Namespace
    //     import a = |b.c|; // Value, type, namespace
    //     import a = |b.c|.d; // Namespace
    if (entityName.kind === SyntaxKind.Identifier && isRightSideOfQualifiedNameOrPropertyAccess(entityName)) {
        entityName = entityName.parent as QualifiedName;
    }
    // Check for case 1 and 3 in the above example
    if (entityName.kind === SyntaxKind.Identifier || entityName.parent.kind === SyntaxKind.QualifiedName) {
        return resolveEntityName(entityName, SymbolFlags.Namespace, /*ignoreErrors*/ false, dontResolveAlias);
    }
    else {
        // Case 2 in above example
        // entityName.kind could be a QualifiedName or a Missing identifier
        Debug.assert(entityName.parent.kind === SyntaxKind.ImportEqualsDeclaration);
        return resolveEntityName(entityName, SymbolFlags.Value | SymbolFlags.Type | SymbolFlags.Namespace, /*ignoreErrors*/ false, dontResolveAlias);
    }
}

I'm not sure why the first case only accepts namespaces.

I'll file a TypeScript issue about this later.

[Gerrit0]

Out of time for this weekend, but it doesn't look like this is very hard to support, at least for this very simple case...