API Documentation v Source Code

[tomwanzek]

In response to a community request, I drew up a TypeScript definition for the d3-sankey module and submitted a PR to DefinitelyTyped

In the process of doing so, I noticed that the API documentation does not appear to be in line with the actual source code. If there is interest, I don't mind preparing a PR to this repo to address the matter.

Most prominently, there are

• layout generator methods, which are not documented size(...) and link(), and
• wide-spread references to the use of accessor functions, when there are none used at present.
• no explanation, of the node/link properties required or mutated by the layout generator (comparable to d3-force simulation nodes/links)

The key TS interface for the layout generator can be found here as part of PR 16051 for comparison.

While I already drafted some JSDoc style comments in the definitions, some of it is geared to the TS world (e.g. additional interfaces, explanation of generics)

However, with some mutual fine tuning, we could align the API documentation comparable to other D3 modules and the TS definitions.

Let me know, if you are interested. Cheers, T.

[tomwanzek]

I have submitted PR #23 to this repo to address the above issues. To the best of my reading, it reflects the currently implemented source code. Language-wise the update compares to other API docs (e.g. d3-force).

I suppose, if there was a plan to change the layout generator to an implementation which supports the use of accessor functions, e.g. to relate links to their source/target more flexibly, the documentation should be updated at such time.

Open to suggestions, hope this helps. T

[mbostock]

Made changes. Should be good now?