Open cgranade opened 4 years ago
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.
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!
@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.
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:Expected behavior
Expected that the above would typeset the same as replacing the
# See Also
block with:Screenshots
Actual rendering: