Allow for more time-robust links to code

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

When writing documentation (in a wiki or README) we sometimes want to reference code in the code-base. Currently we can reference a file or a line within the file.

This issue proposes to allow the possibility to reference code entities (methods, classes, variables) within the file not just the line.

Problem statement

However, most of the time we don't want to reference a line, but a particular method, class, variable or other entity within the code. When documentation is pointing to a line as soon as the code file changes the documentation is broken unless it gets updated. To reduce the effort of maintaining documentation references, it would be nice to introduce the possibility to sematically reference parts of the code.

For example:

Here is a link to my codebase:

This (at time of writing) points to a method nestedWithScoreMode . However, if I change the code, then anything referencing that line (but with the intent to reference that method. in particular this ticket) will be broken.

Proposal

The proposal would allow to reference items within the code reference by name. This could end up with something like:

Possible first implementation

A first step could focus on methods (functions) and then work iteratively for other entities. In this case we have a generated HTML code that looks like:

image.png

Whenever a span of class hljs-title.function is generated, just add at the same time an attribute id using the name of the function as value. This may lead to multiple identical ids within the same page. To initially address this we have different options:

  • Accept it (letting the browser decide what to do with the ambiguity)
  • Skip the id creation if another id exists
  • Suffix a number in the case of conflicts
Edited by 🤖 GitLab Bot 🤖