purs docs hyperlinked identifiers, modules

[jamesdbrock]

Haddock has features which allow us to link to other modules in documentation:

https://www.haskell.org/haddock/doc/html/ch03s08.html#idm140354810770608

3.8.7. Hyperlinked Identifiers

Referring to a Haskell identifier, whether it be a type, class, constructor, or function, is done by surrounding it with single quotes:

-- | This module defines the type 'T'.

If there is an entity T in scope in the current module, then the documentation will hyperlink the reference in the text to the definition of T (if the output format supports hyperlinking, of course; in a printed format it might instead insert a page reference to the definition).

It is also possible to refer to entities that are not in scope in the current module, by giving the full qualified name of the entity:

-- | The identifier 'M.T' is not in scope

3.8.9. Linking to modules

Linking to a module is done by surrounding the module name with double quotes:

-- | This is a reference to the "Foo" module.

A basic check is done on the syntax of the header name to ensure that it is valid before turning it into a link but unlike with identifiers, whether the module is in scope isn't checked and will always be turned into a link.

I can't find any existing issue or discussion about this, so I'm raising it here.

This would be nice to have for purs docs. I see references to identifiers in backticks all over Pursuit, and morally it really seems like we should be able to click on those.

As far as the syntax rules, there isn't one obvious best way.

We could just say that any resolvable identifier or module name in backticks gets a hyperlink. This is the one I like.

Or we could have a special convention like Haddock, or like GitHub's relative links in markup files.

[hdgarrood]

This has occurred to me and I want to do it at some point too, but it's low priority for me.