Facility for keeping source code line numbers synced in the documentation

[joonas-fi]

Something like pipeline: search line numbers of interesting places in code -> database of line numbers for interesting places -> see that documentation has up-to-date links for those URLs

We could also extract that database to machine-readable DB so we could build a URL redirect service like "link to source code for main entrypoint of this project" where the redirect service could access that machine-readable file and then redirect to that line number in GitHub (and such) UI

[joonas-fi]

Prior art:

• https://docs.github.com/en/repositories/working-with-files/using-files/getting-permanent-links-to-files
• https://blog.jetbrains.com/writerside/2022/01/the-holy-grail-of-always-up-to-date-documentation/#automate-wisely

Do not hardcode shortcuts — we reference them from the special artifact that in turn extracts them from the product source code.

Cursory glance reveals no such solution in the ecosystem

[joonas-fi]

Maybe compute a kind of source map (actually symbol => (file, line number) pairs).

Store this "source map" in the container image.

Then have a webservice, something like xs.fi/softwarename/version/symbolname download that source map from softwarename/version image ref, then use that source map to resolve symbolname to filename and line number, then finally we have all the pieces:

• repo URL (OCI image metadata)
• repo revision (OCI image metadata)
• source file
• line number

=> we can then redirect to the repo UI for that line.

[joonas-fi]

Alternatives

Automatically generate structure like functions to filename and line

Source maps

Javascript source maps could in theory be used.

Ctags

• https://github.com/jstemmer/gotags
• https://github.com/universal-ctags/ctags

LSIF

https://code.visualstudio.com/blogs/2019/02/19/lsif#:~:text=The%20LSIF%20defines%20a%20standard,without%20running%20a%20language%20server.

Manually annotate "code bookmarks"

Pro of this approach is that it supports marking any section you like, be it function, global variable, local variable, list of imports etc etc. It also doesn't pollute the DB with all symbols but instead carefully opt-in symbols. Also it's one layer of indirection - you rename a function it doesn't break links when the human-came-up-with-symbol-name can be a permalink.

There doesn't seem to be a ready tool or a standard file format for this. But a tool should be easy to make.

WIP: https://github.com/function61/turbobob/tree/feature/code-bookmarks