Skip to content
Snippets Groups Projects

Reference filters for code objects

    • Open Issue created by Alex Kalderimis @alexkalderimis

    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:

    In the {{code:rb:Foo}} class we can call the {{code:rb:Foo#bar}} method.

    And would be equivalent to:

    In the [Foo](https://gitlab.com/gitlab-org/-/blobs/master/app/models/foo.rb#L123) class ...

    Other languages might use different syntax:

    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, 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

    Availability & Testing

    What does success look like, and how can we measure that?

    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

    Edited by Alex Kalderimis

    Designs

      Child items ...

      2. Activity

      Please register or sign in to reply