Add in-code documentation anchors
Release notes
Add in-code documentation anchors that are linkable
Problem to solve
Currently it's impossible to add a link inside of code that has any stickiness. Over time code will move around making any external documentation references impossible to maintain. What we'd like to see is some form of anchors that can be linked from code that is part of a comment within any language (java being the immediate target). The code would look like this:
Intended users
Delaney,Sam - used to align service patterns for all similar code through the company. We need a way to make this viable where it connects an Architectural Pattern from a doc source (i.e. a wiki) directly to the pattern in code. In this case Delaney & Sam are constantly working to flush out patterns that should be used for common pieces of code. These patterns will evolve over time. They want to ensure that the patterns are written in a very tight, closed loop way, where the design/architecture/best practices are fully flushed out and connect to rich code examples. Ultimately they want to ensure that the implementors / maintainers of the code are using the best-practices.
AND
Sasha,Simone,Devon - used by individual contributors to ensure that new pieces code use the approved patterns for the organization. This ensures that the code fits with the architecture and that the implementors use a proven model rather than re-inventing the wheel. By connecting the patterns directly to the code-base where it is implemented this ensures that it is easy to decipher the implementation of the pattern and not leave things up to interpretation.
User experience goal
public class Foo {
/**
* #external-anchor:FooRunIt
*/
public void runIt() {
...
...
// #external-anchor:FooRunItRunSomethingOfSubstance
runSomethingOfSubstance();
...
...
}
}After this code is merged to gitlab it would then be linkable via something like https://gitlab/group/project/com/example/Foo#FooRunIt and https://gitlab/group/project/com/example/Foo#FooRunItRunSomethingOfSubstance
Proposal
Analyze all files checked into gitlab to allow for anchors to be easily linkable. These can be stored or they can be on the fly.
Further details
Benefits discussed with personas
Permissions and Security
Anyone who can commit code should be able to add anchors. Permissions do not change otherwise.
Documentation
Availability & Testing
Available Tier
Free
What does success look like, and how can we measure that?
Anchors within the code base to be linkable in a browser.
What is the type of buyer?
This is a feature within the existing offering