Automatically update source links in documentation

[mootari]

(This is a follow-up to d3/d3-zoom#58.)

Source links in module documentations reference the master branch and are prone to breaking. As stated by @mbostock the reasoning was:

This was a consideration when the source links were added, but I’d rather have broken links than no links at all. [...] If the source links are off by a few lines, usually it won’t be that hard to find the definition.

The goal of this issue is to create a script that:

• identifies the commit that was originally referenced by a source link,
• finds the new position of that line in the latest revision,
• replaces the old source link with an updated one that references the new line position (and optionally handles code moved between files)
• prints a list of original referenced line vs new referenced line for manual review.

[mbostock]

Another solution to this problem would be something like Javadoc, where the documentation is embedded directly in the source code.

In the past, I’ve argued against in-code documentation for JavaScript because it makes the source bigger, requires fiddly formatting, and muddies the two audiences (internal maintainers and external users). But then again we have minified builds and all abstractions are leaky.

(In 3.x and below, I maintained the API Reference in the wiki to make it easier for others to contribute. However, using a wiki for API documentation had major downsides, most significantly that the state of the wiki wasn’t tied to the current state of the code, and there was no way to view the past API reference for a given release. Putting the API reference into the repository means that pull requests and branches can update the documentation concurrently with the code.)

In the past I found JSDoc to be too rigid for some of the patterns D3 uses (such as scales, which effectively extend Function), and I like the simplicity of generating everything to a single Markdown file that can be hosted directly in the repo. On the other hand, it’d be nice not to maintain another tool, and using GitHub-hosted Markdown has limitations (e.g., the anchor fragment links to jump around the page don’t work on the mobile view, and GitHub doesn’t seem willing to fix it).

documentation.js looks nice and I have much respect for tmcw & jfirebaugh.

[mootari]

That is an excellent idea! Having JSDoc would make the code more accessible and allow better IDE support. Which d3 module would be diverse/complex enough that it could be used as a representative test case?

[mootari]

I hacked together a node script: https://gist.github.com/mootari/65c6e37037b358232b82d463993115de

Doesn't do command line args yet but seems to work well otherwise.

Edit: File was not properly updated. Fixed.

[mbostock]

Neat! Now have it generate a patch so we can pipe it to git apply. :)