Link to type parameters on functions/classes

Resolves #2322
TypeStrong · Dec 30, 2023 · a0aa060 · a0aa060
1 parent 5e108b6
commit a0aa060
Show file tree

Hide file tree

Showing 23 changed files with 281 additions and 125 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,8 @@
 
 ## Features
 
+-   Type parameters on functions/classes can will now link to the "Type Parameters" section, #2322.
+    Type parameters have also been changed to have a distinct color from type aliases when rendering, which can be changed with custom CSS.
 -   TypeDoc now provides warnings if a signature comment is directly specified on a signature and contains `@param` tags which do not apply, #2368.
 -   Extended reflection preview view for interfaces to include type parameters, #2455.
 -   Added special cases for converting methods which are documented as returning `this` or accepting `this` as a parameter, #2458.

diff --git a/src/lib/converter/context.ts b/src/lib/converter/context.ts
@@ -308,9 +308,6 @@ export class Context {
         );
     }
 
-    /**
-     * @param callback  The callback function that should be executed with the changed context.
-     */
     public withScope(scope: Reflection): Context {
         const context = new Context(
             this.converter,

diff --git a/src/lib/converter/converter.ts b/src/lib/converter/converter.ts
@@ -254,7 +254,6 @@ export class Converter extends ChildableComponent<
      * Convert the given TypeScript type into its TypeDoc type reflection.
      *
      * @param context  The context object describing the current state the converter is in.
-     * @param referenceTarget The target to be used to attempt to resolve reference types
      * @returns The TypeDoc type reflection representing the given node and type.
      * @internal
      */

diff --git a/src/lib/models/comments/comment.ts b/src/lib/models/comments/comment.ts
@@ -387,7 +387,6 @@ export class Comment {
      * Return the first tag with the given name.
      *
      * @param tagName  The name of the tag to look for.
-     * @param paramName  An optional parameter name to look for.
      * @returns The found tag or undefined.
      */
     getTag(tagName: `@${string}`): CommentTag | undefined {

diff --git a/src/lib/models/reflections/abstract.ts b/src/lib/models/reflections/abstract.ts
@@ -440,7 +440,7 @@ export abstract class Reflection {
     /**
      * Return a child by its name.
      *
-     * @param names The name hierarchy of the child to look for.
+     * @param arg The name hierarchy of the child to look for.
      * @returns The found child or undefined.
      */
     getChildByName(arg: string | string[]): Reflection | undefined {

diff --git a/src/lib/models/types.ts b/src/lib/models/types.ts
@@ -912,23 +912,15 @@ export class ReferenceType extends Type {
         context: Context,
         name?: string,
     ) {
-        // Type parameters should never have resolved references because they
-        // cannot be linked to, and might be declared within the type with conditional types.
-        if (symbol.flags & ts.SymbolFlags.TypeParameter) {
-            const ref = ReferenceType.createBrokenReference(
-                name ?? symbol.name,
-                context.project,
-            );
-            ref.refersToTypeParameter = true;
-            return ref;
-        }
-
         const ref = new ReferenceType(
             name ?? symbol.name,
             new ReflectionSymbolId(symbol),
             context.project,
             getQualifiedName(symbol, name ?? symbol.name),
         );
+        ref.refersToTypeParameter = !!(
+            symbol.flags & ts.SymbolFlags.TypeParameter
+        );
 
         const symbolPath = symbol?.declarations?.[0]
             ?.getSourceFile()

diff --git a/src/lib/output/themes/default/DefaultTheme.tsx b/src/lib/output/themes/default/DefaultTheme.tsx
@@ -9,6 +9,7 @@ import {
     SignatureReflection,
     ReflectionCategory,
     ReflectionGroup,
+    TypeParameterReflection,
 } from "../../../models";
 import { RenderTemplate, UrlMapping } from "../../models/UrlMapping";
 import type { PageEvent } from "../../events";
@@ -121,7 +122,6 @@ export class DefaultTheme extends Theme {
      * Create a new DefaultTheme instance.
      *
      * @param renderer  The renderer this theme is attached to.
-     * @param basePath  The base path of this theme.
      */
     constructor(renderer: Renderer) {
         super(renderer);
@@ -336,7 +336,11 @@ export class DefaultTheme extends Theme {
      * @param container   The nearest reflection having an own document.
      */
     static applyAnchorUrl(reflection: Reflection, container: Reflection) {
-        if (!(reflection instanceof DeclarationReflection) && !(reflection instanceof SignatureReflection)) {
+        if (
+            !(reflection instanceof DeclarationReflection) &&
+            !(reflection instanceof SignatureReflection) &&
+            !(reflection instanceof TypeParameterReflection)
+        ) {
             return;
         }
 

diff --git a/src/lib/output/themes/default/partials/type.tsx b/src/lib/output/themes/default/partials/type.tsx
@@ -276,8 +276,11 @@ const typeRenderers: {
 
         if (reflection) {
             if (reflection.kindOf(ReflectionKind.TypeParameter)) {
-                // Don't generate a link as it will always point to this page.
-                name = <span class="tsd-signature-type tsd-kind-type-parameter">{reflection.name}</span>;
+                name = (
+                    <a class="tsd-signature-type tsd-kind-type-parameter" href={context.urlTo(reflection)}>
+                        {reflection.name}
+                    </a>
+                );
             } else {
                 name = renderUniquePath(context, reflection);
             }
@@ -290,7 +293,7 @@ const typeRenderers: {
         } else if (type.refersToTypeParameter) {
             name = <span class="tsd-signature-type tsd-kind-type-parameter">{type.name}</span>;
         } else {
-            name = <span class="tsd-signature-type ">{type.name}</span>;
+            name = <span class="tsd-signature-type">{type.name}</span>;
         }
 
         if (type.typeArguments?.length) {

diff --git a/src/lib/output/themes/default/partials/typeParameters.tsx b/src/lib/output/themes/default/partials/typeParameters.tsx
@@ -11,8 +11,11 @@ export function typeParameters(context: DefaultThemeRenderContext, typeParameter
                     {typeParameters?.map((item) => (
                         <li>
                             <h4>
-                                {item.flags.isConst && "const "}
-                                {item.varianceModifier ? `${item.varianceModifier} ` : ""}
+                                <a id={item.anchor} class="tsd-anchor"></a>
+                                {item.flags.isConst && <span class="tsd-signature-keyword">const </span>}
+                                {item.varianceModifier && (
+                                    <span class="tsd-signature-keyword">{item.varianceModifier} </span>
+                                )}
                                 <span class="tsd-kind-type-parameter">{item.name}</span>
                                 {!!item.type && (
                                     <>

diff --git a/src/lib/output/themes/lib.tsx b/src/lib/output/themes/lib.tsx
@@ -108,7 +108,9 @@ export function renderTypeParametersSignature(
                     <>
                         {item.flags.isConst && <span class="tsd-signature-keyword">const </span>}
                         {item.varianceModifier ? `${item.varianceModifier} ` : ""}
-                        <span class="tsd-signature-type tsd-kind-type-parameter">{item.name}</span>
+                        <a class="tsd-signature-type tsd-kind-type-parameter" href={context.urlTo(item)}>
+                            {item.name}
+                        </a>
                     </>
                 ))}
                 <span class="tsd-signature-symbol">{">"}</span>

diff --git a/src/lib/serialization/serializer.ts b/src/lib/serialization/serializer.ts
@@ -64,7 +64,6 @@ export class Serializer extends EventDispatcher {
     /**
      * Same as toObject but emits {@link Serializer.EVENT_BEGIN} and {@link Serializer.EVENT_END} events.
      * @param value
-     * @param eventData Partial information to set in the event
      */
     projectToObject(
         value: ProjectReflection,

diff --git a/src/lib/utils/loggers.ts b/src/lib/utils/loggers.ts
@@ -100,7 +100,6 @@ export class Logger {
      * Log the given verbose message.
      *
      * @param text  The message that should be logged.
-     * @param args  The arguments that should be printed into the given message.
      */
     verbose(text: string) {
         this.log(this.addContext(text, LogLevel.Verbose), LogLevel.Verbose);
@@ -115,7 +114,6 @@ export class Logger {
      * Log the given warning.
      *
      * @param text  The warning that should be logged.
-     * @param args  The arguments that should be printed into the given warning.
      */
     warn(text: string, node?: ts.Node): void;
     warn(text: string, pos: number, file: MinimalSourceFile): void;
@@ -130,7 +128,6 @@ export class Logger {
      * Log the given error.
      *
      * @param text  The error that should be logged.
-     * @param args  The arguments that should be printed into the given error.
      */
     error(text: string, node?: ts.Node): void;
     error(text: string, pos: number, file: MinimalSourceFile): void;

diff --git a/src/test/converter/alias/specs.json b/src/test/converter/alias/specs.json
@@ -40,8 +40,9 @@
         "type": "conditional",
         "checkType": {
           "type": "reference",
-          "target": -1,
+          "target": 9,
           "name": "T",
+          "package": "typedoc",
           "refersToTypeParameter": true
         },
         "extendsType": {
@@ -126,8 +127,9 @@
         "type": "conditional",
         "checkType": {
           "type": "reference",
-          "target": -1,
+          "target": 11,
           "name": "T",
+          "package": "typedoc",
           "refersToTypeParameter": true
         },
         "extendsType": {
@@ -147,14 +149,19 @@
         },
         "trueType": {
           "type": "reference",
-          "target": -1,
+          "target": {
+            "sourceFileName": "src/test/converter/alias/alias.ts",
+            "qualifiedName": "U"
+          },
           "name": "U",
+          "package": "typedoc",
           "refersToTypeParameter": true
         },
         "falseType": {
           "type": "reference",
-          "target": -1,
+          "target": 11,
           "name": "T",
+          "package": "typedoc",
           "refersToTypeParameter": true
         }
       }
@@ -222,8 +229,9 @@
                   "flags": {},
                   "type": {
                     "type": "reference",
-                    "target": -1,
+                    "target": 6,
                     "name": "T",
+                    "package": "typedoc",
                     "refersToTypeParameter": true
                   }
                 },
@@ -235,8 +243,9 @@
                   "flags": {},
                   "type": {
                     "type": "reference",
-                    "target": -1,
+                    "target": 6,
                     "name": "T",
+                    "package": "typedoc",
                     "refersToTypeParameter": true
                   }
                 }

diff --git a/src/test/converter/class/specs-with-lump-categories.json b/src/test/converter/class/specs-with-lump-categories.json
@@ -4115,8 +4115,10 @@
                       },
                       "type": {
                         "type": "reference",
-                        "target": -1,
+                        "target": 170,
                         "name": "T",
+                        "package": "typedoc",
+                        "qualifiedName": "GenericClass.T",
                         "refersToTypeParameter": true
                       }
                     }
@@ -4127,8 +4129,10 @@
                     "typeArguments": [
                       {
                         "type": "reference",
-                        "target": -1,
+                        "target": 170,
                         "name": "T",
+                        "package": "typedoc",
+                        "qualifiedName": "GenericClass.T",
                         "refersToTypeParameter": true
                       }
                     ],
@@ -4164,8 +4168,10 @@
               ],
               "type": {
                 "type": "reference",
-                "target": -1,
+                "target": 170,
                 "name": "T",
+                "package": "typedoc",
+                "qualifiedName": "GenericClass.T",
                 "refersToTypeParameter": true
               }
             },
@@ -4197,8 +4203,10 @@
                 "type": "array",
                 "elementType": {
                   "type": "reference",
-                  "target": -1,
+                  "target": 170,
                   "name": "T",
+                  "package": "typedoc",
+                  "qualifiedName": "GenericClass.T",
                   "refersToTypeParameter": true
                 }
               }
@@ -4253,8 +4261,10 @@
                   ],
                   "type": {
                     "type": "reference",
-                    "target": -1,
+                    "target": 170,
                     "name": "T",
+                    "package": "typedoc",
+                    "qualifiedName": "GenericClass.T",
                     "refersToTypeParameter": true
                   }
                 }
@@ -5046,8 +5056,10 @@
                     "typeArguments": [
                       {
                         "type": "reference",
-                        "target": -1,
+                        "target": 214,
                         "name": "T",
+                        "package": "typedoc",
+                        "qualifiedName": "GenericClass.T",
                         "refersToTypeParameter": true
                       }
                     ],
@@ -5073,8 +5085,10 @@
               ],
               "type": {
                 "type": "reference",
-                "target": -1,
+                "target": 214,
                 "name": "T",
+                "package": "typedoc",
+                "qualifiedName": "GenericClass.T",
                 "refersToTypeParameter": true
               }
             }