Possible linking bug in docs

[coconutlad]

Hi, I think there may be a bug in linking within the docs for Sugiyama layering operators.

The page for LayeringOperator has possible inconsistencies with its links.

The hierarchy section looks like this:

LayeringOperator CoffmanGrahamOperator LongestPathOperator SimplexOperator

where simplex operator links to the sugiyama layering simplex operator.

On the other hand, the section under "Callable" has slightly different links:

LongestPathOperator - minimum height layout CoffmanGrahamOperator - fixed node with layout SimplexOperator - minimize the length of edges TopologicalOperator - topological layering (one node per layer)

Here the LongestPathOperator and CoffmanGrahamOperator link to their respective sections under sugiyama layering but the SimplexOperator and TopologicalOperator link to the sugiyama coord section.

In case this is a bug, maybe it's because the "link id" for both of the simplex operators have the same name?
coord and layering Sorry I couldn't figure out much else, I'm not familiar with this docs generation tool.

[erikbrinkman]

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.

[coconutlad]

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.

[erikbrinkman]

In the lastest version, I changed to a flat documentation structure that typedoc prefers, and changed the names of things to be more verbose, but legible in a flat module structure. This also fixed the aliasing issue.