Add a "default" badge to renamed symbols

[felipecrs]

ideally it'd be nice to have something like this where the (default) is there and informing you that, yes, this is the default export and not a named export BUT also being out of the way enough to not clutter it? idk the technical feasibility of this tho

you can sorta do this now with the @exports default or some other @summary THIS IS THE DEFAULT EXPORT in your jsdoc comment but it's not quite the same lol

/**
 * @exports default
 * @name default
 * @summary THIS IS THE DEFAULT EXPORT
 * @defaultExport
 */
export default function assign<T extends object, U extends object>(o1: T, o2: U): T & U {
  return Object.assign(o1, o2)
}

Originally posted by @jcbhmr in #14 (comment)

[felipecrs]

I totally agree with this one, but it is a different topic so I extracted it to its own issue.

I also think we should add this badge by default to all renamed symbols, not needing users to opt-in with some JSDoc tag.

We need to investigate how feasible it is with TypeDoc, and if not feasible at all, the first step would be to create a feature request there.

[felipecrs]

@Gerrit0 do you have any idea if it is possible for plugins to contributes badges like the

which can be seem here for example?

In our case, we'd like to add a "Default" badge.

[Gerrit0]

TypeDoc renders reflection flags (small static set of options) and modifier tags for the reflection there. refl.comment.modifierTags.add("@default") will get you pretty close, though you'll want to do that to the signature comment instead if the reflection is a function.

Flags are not rendered in the index, however. I'm not aware of any nice way to get them to show up there. It's really not designed to do that.

[Gerrit0]

You'll probably also want a listener on BOOTSTRAP_END to ensure @default is defined as a modifier tag like is done in this example plugin: TypeStrong/typedoc#2273 (comment)

[felipecrs]

That's very helpful @Gerrit0, we will play with it. Thank you so much!

[jcbhmr]

i got something to appear!

https://stackblitz.com/edit/stackblitz-starters-qfzmql?file=index.js

js

import { Application, Converter, Comment, ReflectionFlag } from 'typedoc';

/** @param {Readonly<import('typedoc').Application>} app */
export function load(app) {
  app.on(Application.EVENT_BOOTSTRAP_END, () => {
    const tags = new Set(app.options.getValue('inlineTags'));
    tags.add('@default');
    app.options.setValue('inlineTags', [...tags]);
  });
  /**
   * @param {import('typedoc').Context} context
   * @param {import('typedoc').DeclarationReflection} reflection
   */
  function handleCreateDeclaration(context, reflection) {
    if (['default', 'export='].includes(reflection.name) && reflection.parent) {
      let name = reflection.parent.getFriendlyFullName();
      name = name.split('/').at(-1);
      name = name.trim();
      name = name.replace(/[_.\- ]+(\w)/g, (m, x) => x.toUpperCase());
      reflection.name = name;

      reflection.setFlag(ReflectionFlag.DefaultValue, true);
      reflection.setFlag(ReflectionFlag.ExportAssignment, true);
      console.log(reflection.flags);
      reflection.comment ??= new Comment();
      reflection.comment.summary.unshift({
        kind: 'inline-tag',
        tag: '@default',
      });
      reflection.comment.modifierTags.add('@default');
      console.log('reflection.comment', reflection.comment);

      for (const r of reflection.getAllSignatures()) {
        r.setFlag(ReflectionFlag.DefaultValue, true);
        r.setFlag(ReflectionFlag.ExportAssignment, true);
        console.log(r.flags);
        r.comment ??= new Comment();
        r.comment.summary.unshift({ kind: 'inline-tag', tag: '@default' });
        r.comment.modifierTags.add('@default');
        console.log('r.comment', r.comment);
      }
    }
  }
  app.converter.on(Converter.EVENT_CREATE_DECLARATION, handleCreateDeclaration);
}

what did it was this:

      reflection.setFlag(ReflectionFlag.DefaultValue, true);
      reflection.setFlag(ReflectionFlag.ExportAssignment, true);

[jcbhmr]

this seems to work too and you can insert any text you want into it:

      reflection.flags.push('goobledegook');

https://stackblitz.com/edit/stackblitz-starters-23xcer?file=index.js

[jcbhmr]

another trick i figured out is that you can override the .kind and set it to ReflectionKind.Property which effectively forces it to be on the module index page instead of in a separate page. this can be nice since it is the default export after all and should probably be on the main module index page and not hidden in a sub-page

☝ ill admit, even just that with the still weird export= looks pretty good.

js

import { Converter, ReflectionKind } from 'typedoc';

/** @param {Readonly<import('typedoc').Application>} app */
export function load(app) {
  /**
   * @param {import('typedoc').Context} context
   * @param {import('typedoc').DeclarationReflection} reflection
   */
  function handleCreateDeclaration(context, reflection) {
    if (['default', 'export='].includes(reflection.name) && reflection.parent) {
      reflection.kind = ReflectionKind.Property;
    }
  }
  app.converter.on(Converter.EVENT_CREATE_DECLARATION, handleCreateDeclaration);
}

https://stackblitz.com/edit/stackblitz-starters-p9teo1

[felipecrs]

It looks amazing!

[felipecrs]

BTW my preferred option is to keep the current behavior of this plugin but add the "Default" badge to the renamed properties.