Automatic links

[lawmurray]

Add automatic linking to entity signatures. When the signature appears in the docs as, for example:

TypeA f(const TypeB& b, const TypeC& c);

the types TypeA, TypeB and TypeC ought to link to their respective documentation pages, if they exist. An example is available in the Birch documentation for the Buffer class, noting that known types are linked throughout¹.

Ideally this would be achieved by using the existing Tree-sitter parser to pluck out type identifiers and link them if recognized. If that proves too tricky, a fallback would be regular expressions to find and replace identifiers that are recognized as types.

Some further context. The Doxygen approach to automatic link generation is as follows:

All words in the documentation that correspond to a documented class and contain at least one non-lower case character will automatically be replaced by a link to the page containing the documentation of the class. If you want to prevent that a word that corresponds to a documented class is replaced by a link you should put a % in front of the word.

Personally, I have always found this too aggressive, and end up using a lot of % to prevent Doxygen from creating links, which I can typically only identify when editing the final result. This becomes laborious. I would prefer that Doxide automatically link in signatures, as suggested in this ticket, but that it does not create automatic links in the documentation itself. Rather, links can be added where appropriate with Markdown, or in future, perhaps a @command can be added for the purpose.

Footnotes

1. Doxide was something of a spin-off from the way Birch handles its documentation. Birch is a different language with a different parser though. ↩

[lawmurray]

No one is currently assigned to this issue. Volunteers welcome! 🙂

[lawmurray]

Once concept support is available (see #10), would be good to link them too.