Possible linking bug in docs about d3-dag HOT 3 OPEN

Unfortunately, I think this is probably under the category of known issue. typedoc only supports limited link resolution, despite the tsdoc spec generally supporting qualified links. This is also partially a problem with the way d3-dag is structured. It's both a modular library that anyone can use as a typescript project, hence the goal to document and export internal things, but it's also a front end library with only one entry point index.ts. This structure isn't good for typedoc.

As I see it, there are three solutions:

1. wait until typedoc fixes this - it's been years so maybe not the best option
2. rename the internal types to be unambiguous - I dislike this because it's technically breaking, although only to people using the ES6 syntax, it's also more verbose, but maybe that's not a bad thing. I'm leaning towards this as the best option, that way I don't have to rename them at export and it solves this problem.
3. link to the unambiguous export names - this will also fix it, but creates a two link problem where you have to click once to get to the exported name, and then again to the internal definition, which isn't great...

I have a few other projects I'm working on that are a little higher priority for me, but I'm planning to put some more cycles here soon, particularly if you end up having comments on interactive dags, because it would be nice to shore up that in terms of the api. If I do that, it probably makes sense to break this internal api as well.

from d3-dag.

Ah, I see. Thanks for the explanation!
Just to confirm, is this because typedoc is using step 4 mentioned here to find the name?

The second solution looks good. Maybe the third one isn't so bad either.
In my opinion, as a beginner, it's helpful to know what the exported name is. Most of the time autocomplete helps find the exported name (e.g. when you want to use SimplexOperator editor autocomplete suggests "layeringSimplex" as you're typing "simplex" while trying to use) but it might be okay to have the first click go to the exported name.
That's just my perspective though.

I'll get back to you regarding interactive dags in that thread. Just been doing some reading about that.

Thanks for clarifying this issue. Please feel free to close it whenever you'd like.

from d3-dag.