Default exports should retain their name

[JasonHK]

Search Terms

default exports

Problem

Currently, the name of default exports will be removed and renamed to default, which could cause confusion like the screenshot below.

The default of payload is default is NOT the default export of this module.

Suggested Solution

If the default export is named (like function named() {...}, class Named {...}, const named = ..., etc.), TypeDoc should retain its name and add a default badge to indicate it's a default export. Any types that referencing it should use the original name as well, and not default.

[Gerrit0]

I am fairly strongly against this - docs should reflect what is actually exported, not what names are used locally to refer to the exports.

However, most people who run into the issue of to many symbols named default are giving TypeDoc a directory to document rather than a single entry point. If you use the TypeDoc command I just sent a PR for, I think you'll find that the docs are far more to your liking.

If this still isn't good enough, you could do the name change with a plugin.

[JasonHK]

I am fairly strongly against this - docs should reflect what is actually exported, not what names are used locally to refer to the exports.

However, most people who run into the issue of to many symbols named default are giving TypeDoc a directory to document rather than a single entry point. If you use the TypeDoc command I just sent a PR for, I think you'll find that the docs are far more to your liking.

If this still isn't good enough, you could do the name change with a plugin.

@Gerrit0 What if it's the reverse? Similar to the screenshot below:

[felipecrs]

This is more like a bug introduced by the newer versions. Before, the proper field name was used rather than default.

Example:

export default class SaveImage extends Command 

With TypeDoc 0.19:

With TypeDoc 0.20:

[Gerrit0]

@Gerrit0 What if it's the reverse? Similar to the screenshot below:

I guess I'd be okay with this... would rather have it be a plugin, but there isn't a good way of doing that right now. It should be possible (and fairly easy) to do with a plugin in 0.22, since that's being planned with extensibility built into the themes.

This is more like a bug introduced by the newer versions. Before, the proper field name was used rather than default.

Only if you consider a generating documentation that accurately reflects your code to be a bug! 0.19 and earlier included an incredible amount of hackiness in order to get results that produced decent docs... 0.20's approach is far superior once you understand how it works. I think your question in #1526 should help with that.

[felipecrs]

So, there is no way to work around it for now, and the best option is to wait for TypeDoc 0.22 and then create a plugin for that?

[Gerrit0]

So, there is no way to work around it for now, and the best option is to wait for TypeDoc 0.22 and then create a plugin for that?

You could create a plugin today - it just won't integrate as cleanly into the architecture. This will rename default exports using their local name, if available, but it doesn't provide any indication that the value was a default export.

// TypeDoc 0.20.x, CC0
const { Converter } = require("typedoc")

exports.load = function({ application }) {
        application.converter.on(Converter.EVENT_CREATE_DECLARATION, (_context, reflection, node) => {
                if (!node || !node.name || reflection.name !== "default") return;

                reflection.name = node.name.getText();
        });
};

[felipecrs]

@Gerrit0 thank you SO MUCH. It's a plugin now: https://github.com/felipecrs/typedoc-plugin-rename-defaults

[claviska]

I found this thread debugging another issue that the plugin doesn't appear to solve. Consider two classes:

// menu.ts
import { event, EventEmitter } from './decorators';

export default class Menu {
  @event() select: EventEmitter<MenuItem>
}

// menu-item.ts
export default class MenuItem {
  // ...
}

The select property on Menu has no mention of EventEmitter in its type arguments. Instead, the name shows up only as default and I haven't found a way to solve for that yet. 😕

Update: I stand corrected...the id points to the respective class, so it's possible to reference that way. Apologies for the noise!

[brandonmpetty]

@Gerrit0 - I don't know the specifics, but the fact that this requires a plugin seems unusual.
Since most of my classes and interfaces are default, it makes the generated docs very painful to look at.
... to the point that this cannot be what anyone would want or expect. I am attaching a screenshot to highlight that point.

Instead of a plugin that has to be maintained by someone in the community, wouldn't it be better to add an optional parameter to "fix" this? Ideally it would have the class / interface name like one would expect, but perhaps also display a visible flag / badge / whatever in the documentation that denotes it is technically "default" under the hood.

[Gerrit0]

You're seeing a bunch of default exports because you are giving TypeDoc a directory to document. You probably don't want to do that. TypeDoc's primary use case is generating documentation for libraries, and is meant to be given the library's entry point to document. Even if the library uses default exports primarily internally, the top level of a library will then give those awfully named "default" exports a real name. TypeDoc will follow any re-exports in order to document your API surface.

[felipecrs]

BTW, typedoc-plugin-rename-defaults v0.2.0 was released with support for TypeDoc 0.21.x.

[Jax-p]

You're seeing a bunch of default exports because you are giving TypeDoc a directory to document. You probably don't want to do that. TypeDoc's primary use case is generating documentation for libraries, and is meant to be given the library's entry point to document. Even if the library uses default exports primarily internally, the top level of a library will then give those awfully named "default" exports a real name. TypeDoc will follow any re-exports in order to document your API surface.

Can you explain that, please? If I enter only one file as an entry point, TypeDoc ignores the rest (does not follow imports) and generates documentation only with README.

---

Example

I have some entry whatever.ts file:

import MyDocumentedClass from "./core/MyDocumentedClass";
import AnotherDocumentedClass from "./core/AnotherDocumentedClass";
new MyDocumentedClass();
new AnotherDocumentedClass();

If I run npx typedoc whatever.ts it results into the empty documentation which contains only readme content. I didn't follow imports. Didn't documented anything.

If i run npx typedoc ./core/*.ts everything is documented (that's fine!) but everything is default.

---

What am I doing wrong? Why it doesn't follow imports?

[Gerrit0]

TypeDoc follows exports, because that's what's visible to your users. Imports are an implementation detail. From the outside, there's no difference between these:

import { actuallyDoIt } from "./helpers"
export function doThings(a, b) {
  return actuallyDoIt(a, b)
}

// ---------

import { actuallyDoIt as someRandomThingToAvoidConflicts } from "./helpers"
export function doThings(a, b) {
  return someRandomThingToAvoidConflicts(a, b)
}

[Simonaester]

How can I use the plugin in a config file? I'm using docusaurus-plugin-typedoc

[Gerrit0]

{
  "plugin": ["./path/to/plugin.js"]
}

Note: paths in config files are relative to the config file

[ArnieGA]

@Gerrit0 thank you SO MUCH. It's a plugin now: https://github.com/felipecrs/typedoc-plugin-rename-defaults

@felipecrs Thank YOU so much for taking the initiative.

[Dayday10]

Against

[Azario16]

@Gerrit0 Good afternoon

I agree with you that there is no point in describing variables that are not exported

But what about the interfaces that are exported and inside which there are parameters from the same directory and they are not exported but are used inside the exported interface

How will a person who opens the documentation understand what exactly needs to be put in the required parameter?

Example:

export interface User {
    detail: Detail
}

interface Detail {
    name: string;
    age: number
}