Stuck on an issue?

Lightrun Answers was designed to reduce the constant googling that comes with debugging 3rd party libraries. It collects links to all the places you might be looking at while hunting down a tough bug.

And, if you’re still stuck at the end, we’re happy to hop on a call to see how we can help out.

[FEATURE] Custom documentation tags

See original GitHub issue

Overview of the feature

Beside the pre-defined tags such as @param or @return, it would be helpful to register some kind of handlers for expanding custom tags specific to the current project or organisation.

Motivation for or Use Case

In our projects, we regularly encounter situations where we would like to add certain pieces of information to many documentation topics across the entire application, or even across various projects within the organization. Examples include, but are not limited to:

a reference to the team responsible for a given feature (think {@team billing})
a reference to our in-house wiki (think {@wiki interesting-topic})
a hint about the product edition a given feature is available in or intended for (think {@edition business})

Surely, nothing prevents us from manually writing these things into the documentation comments. However, each occurrence would include redundant information (e.g. a root URL for internal wiki topics, as well as uniform styling for wiki links) in the source files. If any of that information changes later on (such as said root URL for internal wiki topics), hundreds of occurrences across source files would have to be updated (assuming they all correctly pointed to the old root URL to start with, that is).

Thus, in order to follow the good practice of keeping content (e.g. a wiki topic ID) and presentation (the correctly styled, absolute URL to the wiki page) separate, having some way to globally define and process custom documentation tags in a compodoc instance would be much appreciated.

Related issues

It seems various other users have very similar requests:

#766 - this request unfortunately did not receive any reaction other than being estimated to require approximately 3 hours of work. It was automatically closed and locked by the system after a while.
#128 - this request was said to have been added to some to do list. After that, it did not receive any further reactions and was automatically closed and locked by the system, as well.

(Please do note that I am not complaining about the project devs taking a long time to implement this. I highly appreciate the effort and the useful tool created by it, and I fully understand the developers have a life beside voluntary software development. If anyone, it seems to be the Github issue tracker that fails to acknowledge these factors, and therefore autonomously decides that issues that could not be tackled after a certain amount of time are allegedly just not interesting anymore.)