You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
Document the existing rules, and/or tighten the implementation to use a set of rules if they are currently arbitrary.
If there is exactly one non-empty namespace comment for a namespace, use it.
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.)
The text was updated successfully, but these errors were encountered:
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 */exportinterfaceFoo{}/** Int2 */exportinterfaceFoo{}/** Cls */exportclassFoo{}
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)
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!
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:
tsconfig.json
root? theentryPoints
root? not sure) seem to be favoredBut 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.
The text was updated successfully, but these errors were encountered: