Skip to content

Draft: Documentation tags

crabman requested to merge veloren/dev/veloren:documentation_tags into master
  • By opening this merge request, you agree to release your code and all other changes under the GPL 3 license and to abide by the terms set by this license.
  • Migrations have been added if applicable (migrations are always necessary for removing/renaming item asset files)
  • Significant changes of this merge request have been added to the changelog.

Cross-post from discord by @zesterer

So I've got an idea for a docs thing that I want to try implementing and I'd like some feedback to those that feel like they're still relatively new to the codebase (or, at least, feel like there are large areas that are still a bit of a mystery to them).

The name I'm giving it is the 'tag system'.

We'd introduce a little macro, like the following:

tag!(my_tag_name)

What this does is associate the location it's used in with some higher level docs about a particular concept. For example, you might tag code that handles entity Alignment and damage calculations with a section of the docs that explains how all of those pieces fit together like tag!(alignment).

Tags would need to be declared up-front in a common place (mostly to aid casual discoverability and reduce the chance of two tags accidentally being created for the same concept).

The goal is twofold:

Firstly, the tag name is easy to search throughout the codebase.

Secondly, the macro will - internally - create a unique type associated with that tag so you should be able to right click on it and use your editor's built-in 'find references' or 'go to implementation' feature to navigate through associated parts of the codebase (I need to first double-check that this actually does work through a macro, but I think it should).

  • Hover over tags to get documentation, works
  • Find other uses of the same tag by 'Find references', works
  • Actually write the tags and use them in appropriate places, not done yet

The tag macro can now be invoke like this: tag!(@tag1, @tag2, ...), the reason I decided to add a @ before each tag is to make them grep-friendly, as tags are usually very common words.

Tags are defined as modules in common/src/documentation/tags/, the module-level documentation is what will show up when hovering over a tag.

This unintentionally allows for subtags too, which can simply be defined as submodules of tags and referenced with tag!(@tag1::submodule::subsubmodule).

Usage examples:

Helix (rust-analyzer):
2024-04-09_19-35-19

VSCode (rust-analyzer):
2024-04-09_17-48-34

Edited by crabman

Merge request reports