Checked references to declarations in docstrings

[cbuttner]

When writing documentation comments, you might refer to all sorts of declarations:

• Functions
• Function parameters
• Structs, struct members
• Enums, enum values
• Globals
• Constants
• Etc...

Currently such references are only textual and can easily get out of sync.

There should be a way to reference declarations which are then checked to be valid by the compiler.

[lerno]

Possibly yes, there are ways to do this such as:

/**
 * This will get you the [Foo] value stored in [my_module::global_foo].
 **/

[lerno]

Some concerns:

1. The doc might refer to variables that are private or not imported.
2. If the docs are in a .c3i, the identifiers might refer to identifiers that are in the precompiled library (see 1)
3. The availability of identifiers may depend on compile time evaluation.

I think these are the problems that need to have clear ways to resolve them.

[lerno]

But let's say we do this to some extent. At least we should try to do this for docs to be able to link things up. What format should we use to indicate an identifier? [foo] or {foo} or something else?

[cbuttner]

[foo] is good and intuitive (feels like a common syntax for references).
There should be something analogous to Markdown backticks though so you can add code examples without having to escape the brackets.

[cbuttner]

Some notes: For points 1. and 2. I think it's fine to start with limiting to identifiers that are visible to the current module and see how it works out?

This is conjecture, but I don't expect public APIs to reference private/internal parts much and I don't expect public/private declarations to want reference local declarations in different files.
I'm also guessing that if you reference something from another module, you're likely to already have it imported.

[lerno]

That is probably true yes.