Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Define & improve how namespace comments work for multi-file namespaces #1855

Closed
davidpcaldwell opened this issue Jan 25, 2022 · 2 comments
Closed
Labels
enhancement Improved functionality
Milestone

Comments

@davidpcaldwell
Copy link

Search Terms

namespace comments, multi-file namespaces

Problem

One of the fundamental features provided by TypeScript namespaces is to be able to create Multi-file namespaces, in which the type definitions for a namespace are distributed across multiple files.

As far as I know, when a multi-file namespace is used with TypeDoc, TypeDoc pulls the namespace comment from an arbitrary file declaring the namespace. I have been unable to figure out the exact rules, but believe I have noticed the following:

  • In a single-file namespace, namespace comments work as I would expect,
  • In a multi-file namespace, files that are nearer the root (is it the tsconfig.json root? the entryPoints root? not sure) seem to be favored
  • Within a folder, files earlier in alphabetical order (on macOS) seem to be favored.

But I haven't really figured out the rules, and am using a lot of trial and error to get my namespace comments to be emitted for multi-file namespaces.

Note: My understanding is that VSCode and TypeDoc are both based on TSDoc -- it is interesting to note that VSCode seems to use a different strategy, concatenating all namespace comments for a given namespace (in an order I haven't been able to determine). With namespaces that have children, VSCode happily concatenates the namespace comments for child namespaces (I believe recursively), which is ... not good. (In VSCode, my top-level namespace just has a long word-salad comment in VSCode when I hover over it containing context-free information about the whole project.)

I think concatenating all comments for a given namespace (not counting descendants) might not be an insane solution, though. If you include two namespace comments for the namespace, why not put them together? That might be better than discarding one of them? And if you did it by mistake, presumably you'll notice and get rid of one.

Suggested Solution

I have a few suggestions that overlap.

  1. Document the existing rules, and/or tighten the implementation to use a set of rules if they are currently arbitrary.
  2. If there is exactly one non-empty namespace comment for a namespace, use it.
  3. If there is more than one, concatenate them (which has the advantage, in terms of implementation, of implementing the previous rule also). I don't think order is important; no information loss would result, and if it results from an oversight, the author can correct it. (But for goodness' sake don't do this the way VSCode is doing it, with child namespaces included.)
@davidpcaldwell davidpcaldwell added the enhancement Improved functionality label Jan 25, 2022
@Gerrit0
Copy link
Collaborator

Gerrit0 commented Jan 30, 2022

Today, this is truly arbitrary/dependent on an internal implementation detail of the TypeScript compiler. Since the development of ES Modules, multi-file namespaces have mostly fallen out of favor, with most projects using "real" modules instead. (The TS compiler is a notable exception)... so effort targeting things that basically nobody uses has been essentially nonexistent.

Concatenating comments is... annoying. A dumb += isn't good enough since that wouldn't put summary sections together. TypeDoc used to have logic to grab the longest comment, and use that, which I quietly removed when correcting some other odd behavior with nobody noticing around 2 years ago.

Concatenation is also annoying in other cases. Here, TypeDoc says the comment is "Cls", suggestion 3 would imply it ought to be Int\nInt2\nCls.

/** Int */
export interface Foo {}
/** Int2 */
export interface Foo {}
/** Cls */
export class Foo {}

I think it might be better to give a warning if there is more than one declaration with a comment, and arbitrarily choose one.

Note: My understanding is that VSCode and TypeDoc are both based on TSDoc

This is a common, and unfortunate, misunderstanding since it leads to a lot of frustration... Both VSCode and TypeDoc predate TSDoc by several years, and neither conform to it. It wouldn't help in this case, however... TSDoc does not specify comment discovery, only comment parsing and interpretation of some tags... The rules TSDoc has decided on conflict with several common patterns, and therefore will likely never be fully implemented by either tool. API Extractor the only actively maintained tool I know of that actually follows TSDoc. (Unless you count the eslint plugin that tries to enforce TSDoc, maybe, which I'm pretty sure is maintained by the same people)

@davidpcaldwell
Copy link
Author

Well, going with the longest comment, if that seems acceptable, would certainly be better than the status quo, and I could certainly work with it. So, submitted for your consideration!

@Gerrit0 Gerrit0 added this to To do in TSDoc - v0.23 via automation Feb 15, 2022
@Gerrit0 Gerrit0 moved this from To do to Done in TSDoc - v0.23 Feb 15, 2022
@Gerrit0 Gerrit0 added this to the v0.23 milestone Apr 17, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement Improved functionality
Projects
No open projects
Development

No branches or pull requests

2 participants