Mark functions that are children of classes or interfaces as methods

[fb55]

Search Terms

documentation structure, functions, methods

Problem

Sometimes functions that become members of classes or interfaces still end up as functions. This doesn't make a difference to users, as they look and feel equivalent. It does however make the generated documentation harder to understand; eg. see https://cheerio.js.org/classes/Cheerio.html

This page has both Functions - Traversing and Methods - Traversing as categories, which makes it harder to understand the page.

Suggested Solution

TypeDoc should normalise the children of classes and interfaces to be exclusively methods. TypeDoc already creates copies of them when creating the signatures, meaning this won't lead to actual functions being turned into methods.

I wrote this plugin today to fix the issue:

const td = require('typedoc');

/** @param {td.Application} app - The app. */
exports.load = function (app) {
  app.converter.on(td.Converter.EVENT_CREATE_DECLARATION, updateFnsToMethods);
};

/**
 * @param {td.Context} context - The context.
 * @param {td.DeclarationReflection} reflection - The reflection.
 */
function updateFnsToMethods(context, reflection) {
  if (
    reflection.kindOf(td.ReflectionKind.Function) &&
    reflection.parent?.kindOf(td.ReflectionKind.ClassOrInterface)
  ) {
    // Unset the `Function` flag, set the `Method` flag.
    reflection.kind ^= td.ReflectionKind.Function;
    reflection.kind |= td.ReflectionKind.Method;
  }
}

My suggestion is to include the relevant logic in TypeDoc, as I can't think of a case where this isn't wanted.

[Gerrit0]

That's... an interesting way of structuring an interface. Seems like a reasonable request. Will require adjustments to the comment discovery method so that methods catch comments that "normally" end up on functions.

[Gerrit0]

Well, that was confusing. Apparently this only happens if you are using export const x = () => {} -- regular function declarations are already handled as methods!