<!-- The first four sections: "Problem to solve", "Intended users", "User experience goal", and "Proposal", are strongly recommended, while the rest of the sections can be filled out during the problem validation or breakdown phase. However, keep in mind that providing complete and relevant information early helps our product team validate the problem and start working on a solution. --> ### Problem to solve We support references for various domain objects in GitLab (issues, projects, merge-requests, users, etc), but one thing we reference frequently in markdown is code objects (methods, functions, classes, modules, etc). This could be easier. The current solution is to include a URL such as `https://gitlab.com/gitlab-org/gitlab/-/blobs/master/foo/bar/baz.rb`. This is a poor solution since it has a very low signal to noise ratio (a long common uncommunicative prefix) and is implementation dependent and thus not portable. ### Intended users All personas would benefit from this, as all personas are expected to write and read markdown derived text. ### User experience goal Refering to a code object should use a syntax that is close to the standard syntax for such references. URLs should not be needed. ### Proposal I propose creating reference filters that handle code objects. For Ruby this might look like: ```markdown In the {{code:rb:Foo}} class we can call the {{code:rb:Foo#bar}} method. ``` And would be equivalent to: ```markdown In the [Foo](https://gitlab.com/gitlab-org/-/blobs/master/app/models/foo.rb#L123) class ... ``` Other languages might use different syntax: ```markdown This calls the {{code:clj:some-ns/some-fn}} function, equivalent to {{code:hs:Module.Foo.someFn}} ``` This would use extensible reference filters, with language aware reference parsing added on a language by language basis. ### Further details To implement this, we would need [extensible reference filters](https://gitlab.com/gitlab-org/gitlab/-/issues/217614), and a per-language parsing system. To find references, the most straightforward method might be by reading project specific `tags` files (in standard ctags format) to find code objects. ### Permissions and Security Any user capable of reading the repo should be able to use these reference filters. ### Documentation <!-- See the Feature Change Documentation Workflow https://docs.gitlab.com/ee/development/documentation/workflow.html#for-a-product-change * Add all known Documentation Requirements in this section. See https://docs.gitlab.com/ee/development/documentation/feature-change-workflow.html#documentation-requirements * If this feature requires changing permissions, update the permissions document. See https://docs.gitlab.com/ee/user/permissions.html --> ### Availability & Testing <!-- This section needs to be retained and filled in during the workflow planning breakdown phase of this feature proposal, if not earlier. What risks does this change pose to our availability? How might it affect the quality of the product? What additional test coverage or changes to tests will be needed? Will it require cross-browser testing? Please list the test areas (unit, integration and end-to-end) that needs to be added or updated to ensure that this feature will work as intended. Please use the list below as guidance. * Unit test changes * Integration test changes * End-to-end test change See the test engineering planning process and reach out to your counterpart Software Engineer in Test for assistance: https://about.gitlab.com/handbook/engineering/quality/test-engineering/#test-planning --> ### What does success look like, and how can we measure that? <!-- Define both the success metrics and acceptance criteria. Note that success metrics indicate the desired business outcomes, while acceptance criteria indicate when the solution is working correctly. If there is no way to measure success, link to an issue that will implement a way to measure this. --> ### What is the type of buyer? Any team with the need to reference a lot of code may be interested in this feature. It would integrate well into any code-search or intelli-sense-like features. ### Is this a cross-stage feature? This is primarily a source-code feature, as code objects generally live there. ### Links / references