Document namespaces created from ES2015 modules

[RunDevelopment]

Search Terms

ES2015 modules, import, export

Problem

It's not possible to add a description to namespaces that were created using ES2015 modules.

Example:

export * as Foo from "./foo";

Suggested Solution

Since the namespace is created by export * as namespace, the namespace should be documented there as well.

Example:

/**
 * Description for Foo.
 */
export * as Foo from "./foo";

[Gerrit0]

You can do this today by putting the comment at the top of the file in foo.ts with an @packageDocumentation flag - https://typedoc.org/guides/doccomments/#files

I kind of like being able to put the comment on the export - but that causes other problems:

/** which export does this comment belong to? */
export { x, y } from "./foo"

[RunDevelopment]

Isn't @packageDocumentation ill-fit for this?

In JS/ES/TS there is no concept called "package", it's something that package managers (e.g. NPM) have introduced to the ecosystem. So having the tag for documenting modules be called @packageDocumentation is semantically incorrect.

TSDoc has the following to say about @packageDocumentation:

Used to indicate a doc comment that describes an entire NPM package (as opposed to an individual API item belonging to that package).

Therefore I would argue that namespaces generated by JS'/ES'/TS' module system are API items and should not be documented using this tag. I know that TypeDoc doesn't adhere to TSDoc (yet), so this should only be seen as a second opinion.

---

I also want to say that documenting modules/files isn't what I want to do. I don't want to document the module itself, I want to document the namespace created to export that module. The namespace I care about is created with the export * as name statement.

but that causes other problems:

The reason why your example isn't a problem is that it doesn't create a new namespace. It just creates (and exports) a few variables.

[Gerrit0]

Isn't @packageDocumentation ill-fit for this?

That's a fair point - when I added that behavior a couple years ago I was treating packages and modules as essentially the same thing, and looking for some way to disambiguate comments at the start of files (we can't just take the first comment because that's a license comment in some projects... or at least that's been the argument in the past, I've always been on the fence about caring about those projects... just stick a license file in your project root!) I'm open to changing this behavior.

The reason why your example isn't a problem is that it doesn't create a new namespace.

True - that was somewhat of a bad example - here we introduce a new name for an export, which we might reasonably want to have a comment for... I don't necessarily like requiring users to introduce a second export line just to document it:

export { createElement, createElement as h } from "./jsx"

The new namespace issue is tricky since, in order to document it, we have to resolve the symbol aliases to get to the SourceFile that is used as a namespace... there isn't a great way to get comments after resolving the symbol... I don't really want to add a second "commentSymbol" to convertSymbol... but that might be the way to go.

[RunDevelopment]

The new namespace issue is tricky

I see. In that case, it's better to keep the current solution of documenting modules themselves.

I'm open to changing this behavior.

How about we use the @module tag? Right now, it "overrides an entry point's name", but we could use it to identify the comment that documents the module. The @module will then 1) identify a comment as being about the module and 2) rename the module if a name is given.

Usage will look like this:

/**
 * Some module documentation + renaming.
 * @module foo
 */

/**
 * Some module documentation, no renaming.
 * @module
 */

This is also how JSDoc documents modules.

[Gerrit0]

Tricky != bad idea. After thinking about it for a while, I went ahead and made the necessary changes, incurred a bit of tech debt that should be fixed with 0.21.

Version 0.20.25 will let you specify comments on export declarations, and if an export declaration has a comment, it will override any comment specified for the child node. It also adds support for @module as you suggested, I'll update the website shortly to recommend using @module instead of @packageDocumentation thanks!

[RunDevelopment]

Thank you @Gerrit0!

I have a question regarding the overriding behaviour: Is there a way to view the overridden module comment or will it be discarded/not be present in the generated site?

[Gerrit0]

It depends. If that module is only accessible from the re-export that has an overriding comment, then no, it won't be included anywhere.

If the module is documented more than once (with the module being an entry point or a second re-export not having an overriding comment), then the comment in the module will be used.

[RunDevelopment]

I see. I don't know if it's a good idea to discard the module doc but I also don't have a way of cleverly combining them. As long as this behaviour is clearly communicated on the website, it's ok I guess.

[Gerrit0]

Isn't @packageDocumentation ill-fit for this?

Coming back to this months later... my answer has changed somewhat. Supporting @module is a good idea, but saying that @packageDocumentation is semantically incorrect is not always true. I'm not going to deprecate @packageDocumentation after all, and TypeDoc will continue supporting either @packageDocumentation or @module.

[ArjunAtlast]

Hi, can this @module tag be used to rename the Exports menu item that appears in the documentation.