Documentation generation tool not resolving namespaces correctly in `# See Also` blocks.

[cgranade]

Describe the bug

When generating documentation for /// # See Also blocks, the Q# compiler currently does not resolve identifier names for operations, functions and UDTs to their fully-qualified names. See microsoft/QuantumLibraries#190 for an example.

To Reproduce

Generate documentation for an operation in the Microsoft.Quantum.Arithmetic namespace and with the following comment:

/// # Summary
/// Performs a modular increment of a qubit register by an integer constant.
///
/// Let us denote `increment` by a, `modulus` by N and integer encoded in `target` by y.
/// Then the operation performs the following transformation:
/// \begin{align}
///     \ket{y} \mapsto \ket{(y + a) \operatorname{mod} N}
/// \end{align}
/// Integers are encoded in little-endian format.
///
/// # Input
/// ## increment
/// Integer increment a to be added to y.
/// ## modulus
/// Integer N that mods y + a.
/// ## target
/// Integer y in `LittleEndian` format that `increment` a is added to.
///
/// # See Also
/// - IncrementPhaseByModularInteger
///
/// # Remarks
/// Assumes that the initial value of target is less than N
/// and that the increment a is less than N. 
/// Note that
/// <xref:microsoft.quantum.arithmetic.incrementphasebymodularinteger> implements
/// the same operation in the `PhaseLittleEndian` basis.
operation IncrementByModularInteger(increment : Int, modulus : Int, target : LittleEndian) : Unit {

Expected behavior

Expected that the above would typeset the same as replacing the # See Also block with:

/// # See Also
/// - Microsoft.Quantum.Arithmetic.IncrementPhaseByModularInteger

Screenshots

Actual rendering:

[numpde]

Why is the format of # See Also so rigid -- to avoid typing - @".." or to promote conciseness or ...?

Regarding the issue, I don't understand the "special treatment" but there is no reference to bool lowerCase outside of it (cf. comments in block parsing), while in the example above the content of the # See Also block is not lowercase.

(And anyway, there appears to be a hardcoded ToLowerInvariant under "special treatment".)

Later: PRoposed a change in DocParsingTests to test for potential uppercase refs.

[cgranade]

Why is the format of # See Also so rigid -- to avoid typing - @".." or to promote conciseness or ...?

The /// # See Also section is effectively a light-weight approach to generating lists of related code items but that's pretty similar to C#'s <seealso cref="" /> element. This allows us to generate documentation YAML files that include the seeAlso list expected by docs.microsoft.com:

# Excerpted from:
#     https://github.com/MicrosoftDocs/quantum-docs-pr/blob/master/api/qsharp/microsoft.quantum.simulation.quantumwalkbyqubitization.yml#L44
seeAlso:
- microsoft.quantum.canon.blockencoding
- microsoft.quantum.canon.blockencodingreflection
...

You can always use the @"" in text sections to reference documentation UIDs, as well. Documentation UIDs for Q# reference docs are always lower-case variants of the fully-qualified name being documented.

With respect to why @"" is still supported in # See Also links, that's for backwards compatibility. As per the current version of the Q# language, the /// # See Also block in documentation comments is intended to be a list of names, rather than arbitrary DocFX-Flavored Markdown.

Please let me know if there's anything else I can answer, thanks for all the questions!

[bettinaheim]

@cgranade
This really goes towards having the compiler resolve and verify the content in doc comments in general. It's a dual edged sword, especially with the docs scheme and pipeline that is still somewhat in flux. This hence won't be high on the priority list for a while.