/// <summary>
/// Given a documentation comment describing a Q# user-defined type
/// declaration, writes a Markdown file documenting that UDT
/// declaration to <see cref="OutputPath" />.
/// </summary>
/// <param name="type">The Q# UDT being documented.</param>
/// <param name="docComment">
/// The API documentation comment describing <paramref name="type"/>.
/// </param>
/// <returns>A <see cref="Task"/> representing the result of the asynchronous operation.</returns>
public async Task WriteOutput(QsCustomType type, DocComment docComment)
{
var namedItemDeclarations = type.TypeItems.ToDictionaryOfDeclarations();
// Make a new Markdown document for the type declaration.
var title = $"{type.FullName.Name} user defined type";
var header = new Dictionary <string, object>
{
// DocFX metadata
["uid"] = type.FullName.ToString(),
["title"] = title,
// docs.ms metadata
["ms.date"] = DateTime.Today.ToString(),
["ms.topic"] = "article",
// Q# metadata
["qsharp.kind"] = "udt",
["qsharp.namespace"] = type.FullName.Namespace,
["qsharp.name"] = type.FullName.Name,
["qsharp.summary"] = docComment.Summary,
};
var document = $@"
# {title}
Namespace: [{type.FullName.Namespace}](xref:{type.FullName.Namespace})
{this.packageLink}
{docComment.Summary}
```{this.LanguageMode}
{type.WithoutDocumentationAndComments().ToSyntax()}
```
"
.MaybeWithSection(
"Named Items",
string.Join("\n", type.TypeItems.TypeDeclarations().Select(
item =>
{
(var itemName, var resolvedType) = item;
var documentation =
docComment.NamedItems.TryGetValue(itemName, out var comment)
? comment
: string.Empty;
return($"### {itemName} : {resolvedType.ToMarkdownLink()}\n\n{documentation}");
}
))
)
.MaybeWithSection("Description", docComment.Description)
.MaybeWithSection("Remarks", docComment.Remarks)
.MaybeWithSection("References", docComment.References)
.MaybeWithSection(
"See Also",
string.Join("\n", docComment.SeeAlso.Select(
seeAlso => AsSeeAlsoLink(seeAlso, type.FullName.Namespace)
))
)
.WithYamlHeader(header);
// Open a file to write the new doc to.
await this.WriteAllTextAsync(
$"{type.FullName.Namespace}.{type.FullName.Name}.md",
document
);
}
