Render a type alias as a function

[ritz078]

Thanks a lot for this package. This has been immensely helpful in our documentation efforts.

I am stuck in situation where my function signature alias is being rendered like an object or interface.

export namespace MyNamespace {
  export type MyFunction = (a: number, b: number) => number;
}

This renders as:

If I add @function tag

As you can see the "Type declaration" section is pretty confusing as it becomes a list. Is there a way I can render this as https://typedoc.org/example/functions/sqrt.html ? Since I am exposing the types from namespace, I can't think of any other way than using alias. I appreciate any help.

[Gerrit0]

@function only works on variables. With type aliases, they're rendered like that because type aliases might also need type aliases rendered in multiple places.

/**
 * summary
 * @param a a comment
 * @param b b comment
 * @return Ret
 */
export type gh3002<A> = <T>(a: number, b: number) => number;

I guess we could check <2 sets of type parameters and render it differently...

[Gerrit0]

I spent a little bit of time looking at doing this, and it's unfortunately rather ugly, the content within the "Type declaration" header (which I just noticed isn't consistently capitalized, grumble) is generated by the typeDetails helper, which is used recursively for additional details if there are nested types, so to do this that (rather large) helper would either need to be duplicated into one for the top level and one for a lower level, or gain an option for whether to wrap its content in a list... both of which are rather ugly. Probably doable, but not also something that'll likely end up in a breaking API change.

[ritz078]

Thank you for looking into this.

I tried to write a plugin. I am sure there are some edge cases. Especially handling param separately.

import { 
  Converter, 
  ReflectionKind, 
  Comment,
  PageEvent
} from "typedoc";

/**
 * TypeDoc Plugin: Function-Like Type Alias Renderer
 * 
 * This plugin transforms TypeScript type aliases that represent functions into proper
 * function reflections in the generated documentation. It enables you to document
 * function types as if they were actual functions, with proper parameter documentation,
 * return types, and function categorization.
 * 
 * ## Features
 * 
 * - ✅ Transforms type aliases to functions in documentation
 * - ✅ Preserves all JSDoc tags (@param, @returns, @example, @throws, etc.)
 * - ✅ Maintains proper parameter documentation with inline descriptions
 * - ✅ Appears in sidebar navigation under "Functions" category
 * - ✅ Processes @inheritDoc tags correctly
 * - ✅ Runs early in the conversion pipeline for proper integration
 * 
 * ## Usage
 * 
 * 1. Add the `@functionLike` JSDoc tag to any type alias that represents a function:
 * 
 *    ```typescript
 *    /**
 *     * A function that adds two numbers.
 *     * 
 *     * @param a - The first number
 *     * @param b - The second number
 *     * @returns The sum of a and b
 *     * 
 *     * @functionLike
 *     *\/
 *    export type AddFunction = (a: number, b: number) => number;
 *    ```
 * 
 * 2. The plugin will automatically:
 *    - Transform the type alias to a function reflection
 *    - Preserve all JSDoc documentation
 *    - Attach @param comments to parameters
 *    - Categorize it under "Functions" in navigation
 * 
 * ## How It Works
 * 
 * 1. **Discovery Phase** (EVENT_CREATE_DECLARATION): Identifies type aliases with @functionLike tag
 * 2. **Transformation Phase** (EVENT_RESOLVE_BEGIN, priority -1000): Converts type aliases to functions
 * 3. **Integration**: Uses TypeDoc's existing signature processing and attaches @param comments
 * 
 * ## Technical Details
 * 
 * - **Priority**: -1000 (runs first to ensure availability for @inheritDoc)
 * - **Transformation**: In-place kind change from TypeAlias to Function
 * - **Parameter Handling**: Leverages TypeDoc's existing parameter reflections
 * - **Comment Processing**: Preserves all JSDoc tags except @functionLike and @param
 * 
 * ## Example Output
 * 
 * A type alias like:
 * ```typescript
 * export type MathFunction = (x: number, y: number) => number;
 * ```
 * 
 * Becomes documented as a function with:
 * - Proper function signature
 * - Parameter list with types
 * - Function categorization in sidebar
 * - All JSDoc documentation preserved
 * 
 * It presents like:
 * 
 * ```ts
 * export declare function MathFunction(x: number, y: number): number;
 * ```
 */

// Track function-like type aliases for transformation
const functionLikeSymbols = new Map();

function getOwningModule(context) {
  let refl = context.scope;
  // Go up the reflection hierarchy until we get to a module or project
  while (refl && !refl.kindOf(ReflectionKind.Module | ReflectionKind.Project)) {
    refl = refl.parent;
  }
  return refl;
}

export function load(app) {
  // Register @functionLike as a block tag so TypeDoc recognizes it
  app.converter.on("begin", () => {
    const currentBlockTags = app.options.getValue("blockTags") || [];
    if (!currentBlockTags.includes("@functionLike")) {
      const newBlockTags = [...currentBlockTags, "@functionLike"];
      app.options.setValue("blockTags", newBlockTags);
    }
  });

  // Mark function-like type aliases for transformation
  app.converter.on(Converter.EVENT_CREATE_DECLARATION, (context, reflection) => {
    if ((reflection.kindOf(ReflectionKind.Variable) || reflection.kindOf(ReflectionKind.TypeAlias)) && reflection.comment) {
      const hasTag = reflection.comment.blockTags?.some(tag => tag.tag === "@functionLike");
      if (hasTag) {
        functionLikeSymbols.set(reflection, getOwningModule(context));
      }
    }
  });

  // Transform function-like type aliases to functions
  app.converter.on(Converter.EVENT_RESOLVE_BEGIN, function(context) {
    for (const [typeAlias, owningModule] of functionLikeSymbols) {
      try {
        transformTypeAliasToFunction(typeAlias, context);
      } catch (error) {
        console.error(`Failed to transform ${typeAlias.name}:`, error);
      }
    }
    functionLikeSymbols.clear();
  }, -1000);

  // Remove @functionLike tags from rendered HTML
  app.renderer.on(PageEvent.END, (page) => {
    if (page.contents) {
      // Remove any @functionLike tag displays from the HTML
      page.contents = page.contents.replace(
        /<div class="tsd-tag-functionLike">.*?<\/div>/gs,
        ''
      );
    }
  });
}

/**
 * Transform a variable to function and let TypeDoc handle ALL JSDoc tags naturally
 */
function transformTypeAliasToFunction(variable, context) {
  if (!variable.parent) return;

  // Store the original comment
  const originalComment = variable.comment;
  
  // Remove function-level comment completely to match real functions
  variable.comment = undefined;
  
  // Use TypeDoc's existing signatures and attach @param comments to parameters
  if (variable.type?.declaration?.signatures) {
    // Use TypeDoc's existing signatures
    const existingSignatures = variable.type.declaration.signatures;
    
    // Attach @param comments to parameters in each signature
    for (const sig of existingSignatures) {
      if (sig.parameters) {
        attachParamCommentsToParameters(sig.parameters, originalComment);
      }
      // Update signature name to use the function name instead of "__call"
      sig.name = variable.name;
    }
    
    variable.signatures = existingSignatures;
    
    // Attach cleaned comment to signature (without @param tags to avoid duplication)
    if (existingSignatures.length > 0 && originalComment) {
      const signatureComment = originalComment.clone();
      signatureComment.removeTags("@functionLike");
      signatureComment.removeTags("@param"); // Remove @param to avoid duplication
      existingSignatures[0].comment = signatureComment;
    }
  }
  
  // Change the kind to Function
  variable.kind = ReflectionKind.Function;
  
  // Clear the type property
  if (variable.type) {
    delete variable.type;
  }
}

/**
 * Attach @param comments to existing parameter reflections
 * This is the key insight: TypeDoc creates parameters but doesn't attach @param comments for type aliases
 */
function attachParamCommentsToParameters(parameters, originalComment) {
  if (!parameters || !originalComment) {
    return;
  }

  // Get @param tags from the original comment
  const paramTags = originalComment.blockTags?.filter(tag => tag.tag === "@param") || [];
  
  // Attach @param comments to existing parameter reflections
  parameters.forEach(param => {
    // Find the matching @param tag and attach its comment
    const paramTag = paramTags.find(tag => tag.name === param.name);
    if (paramTag && paramTag.content && paramTag.content.length > 0) {
      // Create a comment with the parameter description
      param.comment = new Comment();
      param.comment.summary = paramTag.content;
    }
  });
}