private void GenerateTitle(DocNamespace ns, StringBuilder output)
{
output.Append(" - [");
output.Append(ns.Name);
output.Append("](##");
output.Append(ns.Name);
output.Append(") *(");
output.Append(ns.Types.Length);
output.Append(")*");
output.AppendLine();
}
private void Generate(DocNamespace ns, StringBuilder output)
{
output.Append("## ");
output.Append(ns.Name);
output.AppendLine();
output.AppendLine();
foreach (DocType dt in ns.Types)
{
GenerateType(dt, output);
}
}
/// <summary>
/// Parses a <see cref="DocNamespace"/> into a <see cref="DocFile"/>.
/// </summary>
/// <param name="ns">The <see cref="DocNamespace"/> to parse.</param>
/// <returns>The transformed <see cref="DocFile"/>.</returns>
private DocFile ProcessNamespace(DocNamespace ns)
{
var result = new DocFile(ns.FileName);
result.AddThenBlankLine(writer.WriteHeading1($"{ns.Name} Namespace"));
result.AddThenBlankLine(ParserUtils.ProcessBreadcrumb(ns));
if (ns.Types.Any(t => t.IsClass))
{
result.AddThenBlankLine(writer.WriteHeading2("Classes"));
var table = new MarkdownTable("Class", "Description");
foreach (var c in ns.Types.Where(t => t.IsClass).OrderBy(t => t.TypeRef.FriendlyName))
{
table.AddRow(writer.WriteLink(c.TypeRef.FriendlyName, c.FileName), c.Description);
result.Files.Add(ProcessType(c));
}
writer.AddRange(result.Markdown, table.CloseTable());
result.AddBlankLine();
}
if (ns.Types.Any(t => t.IsInterface))
{
result.AddThenBlankLine(writer.WriteHeading2("Interfaces"));
var table = new MarkdownTable("Interface", "Description");
foreach (var i in ns.Types.Where(t => t.IsInterface).OrderBy(t => t.TypeRef.FriendlyName))
{
table.AddRow(writer.WriteLink(i.TypeRef.FriendlyName, i.FileName), i.Description);
result.Files.Add(ProcessType(i));
}
writer.AddRange(result.Markdown, table.CloseTable());
result.AddBlankLine();
}
if (ns.Types.Any(t => t.IsEnum))
{
result.AddThenBlankLine(writer.WriteHeading2("Enumerations"));
var table = new MarkdownTable("Enumeration", "Description");
foreach (var i in ns.Types.Where(t => t.IsEnum).OrderBy(t => t.TypeRef.FriendlyName))
{
table.AddRow(writer.WriteLink(i.TypeRef.FriendlyName.NameOnly(), i.FileName), i.Description);
result.Files.Add(ProcessType(i));
}
writer.AddRange(result.Markdown, table.CloseTable());
result.AddBlankLine();
}
return(result);
}
/// <summary>
/// Iterate the types for the namespace.
/// </summary>
/// <param name="docNamespace">The <see cref="DocNamespace"/> to parse into.</param>
private void IterateTypes(DocNamespace docNamespace)
{
foreach (var type in Types.Where(t => t.Namespace == docNamespace.Name))
{
Console.WriteLine($"Parsing type \"{type.FullName}\"...");
var exportedType = new DocExportedType
{
Namespace = docNamespace,
};
ProcessType(type, exportedType);
docNamespace.Types.Add(exportedType);
}
}
/// <summary>
/// Iterate the namespaces of the assembly.
/// </summary>
/// <param name="doc">The <see cref="DocAssembly"/> to iterate.</param>
private void IterateNamespaces(DocAssembly doc)
{
Types = Assembly.GetExportedTypes();
var namespaces = Types.Select(t => t.Namespace).Distinct().OrderBy(n => n);
foreach (var nsp in namespaces)
{
Console.WriteLine($"Parsing namespace \"{nsp}\"...");
var docNamespace = new DocNamespace(nsp)
{
Assembly = doc,
};
IterateTypes(docNamespace);
doc.Namespaces.Add(docNamespace);
}
}
public void ExcludeInaccessible()
{
var elements = new[] { Access.Public, Access.Internal }
.SelectMany(access =>
{
var source = new Source("Tests.qs", QsNullable <string> .Null);
var unit = ResolvedType.New(QsType.UnitType);
var signature = new ResolvedSignature(
Array.Empty <QsLocalSymbol>().ToImmutableArray(),
unit,
unit,
CallableInformation.NoInformation);
var argumentTuple = QsTuple <ArgDeclType> .NewQsTuple(ImmutableArray.Create <QsTuple <ArgDeclType> >());
var callable = new QsCallable(
kind: QsCallableKind.Operation,
fullName: MakeFullName(access + "Operation"),
attributes: ImmutableArray <QsDeclarationAttribute> .Empty,
access,
source: source,
location: ZeroLocation,
signature: signature,
argumentTuple: argumentTuple,
specializations: ImmutableArray.Create <QsSpecialization>(),
documentation: ImmutableArray.Create <string>(),
comments: QsComments.Empty);
var typeItems = QsTuple <QsTypeItem> .NewQsTuple(
ImmutableArray.Create(QsTuple <QsTypeItem> .NewQsTupleItem(QsTypeItem.NewAnonymous(unit))));
var type = new QsCustomType(
fullName: MakeFullName(access + "Type"),
attributes: ImmutableArray <QsDeclarationAttribute> .Empty,
access,
source: source,
location: ZeroLocation,
type: unit,
typeItems: typeItems,
documentation: ImmutableArray.Create <string>(),
comments: QsComments.Empty);
return(new[]
{
QsNamespaceElement.NewQsCallable(callable),
QsNamespaceElement.NewQsCustomType(type)
});
});
var emptyLookup = Array.Empty <ImmutableArray <string> >().ToLookup(x => "");
var ns = new QsNamespace(CanonName, elements.ToImmutableArray(), emptyLookup);
var docNs = new DocNamespace(ns);
var stream = new MemoryStream();
#pragma warning disable 618 // WriteToStream is obsolete.
docNs.WriteToStream(stream, null);
#pragma warning restore 618
var expected = @"### YamlMime:QSharpNamespace
# This file is automatically generated.
# Please do not modify this file manually, or your changes may be lost when
# documentation is rebuilt.
uid: microsoft.quantum.canon
name: Microsoft.Quantum.Canon
operations:
- uid: microsoft.quantum.canon.publicoperation
summary: ''
newtypes:
- uid: microsoft.quantum.canon.publictype
summary: ''
...
";
var actual = Encoding.UTF8.GetString(stream.ToArray());
Assert.Equal(expected, actual);
}
public void ExcludeInaccessible()
{
var elements =
new[] { AccessModifier.DefaultAccess, AccessModifier.Internal }
.SelectMany(access =>
{
var source = NonNullable <string> .New("Tests.qs");
var unit = ResolvedType.New(QsType.UnitType);
var signature = new ResolvedSignature(Array.Empty <QsLocalSymbol>().ToImmutableArray(),
unit,
unit,
CallableInformation.NoInformation);
var argumentTuple = QsTuple <ArgDeclType> .NewQsTuple(ImmutableArray.Create <QsTuple <ArgDeclType> >());
var callable = new QsCallable(kind: QsCallableKind.Operation,
fullName: MakeFullName(access + "Operation"),
attributes: ImmutableArray <QsDeclarationAttribute> .Empty,
modifiers: new Modifiers(access),
sourceFile: source,
location: ZeroLocation,
signature: signature,
argumentTuple: argumentTuple,
specializations: ImmutableArray.Create <QsSpecialization>(),
documentation: ImmutableArray.Create <string>(),
comments: QsComments.Empty);
var typeItems = QsTuple <QsTypeItem> .NewQsTuple(
ImmutableArray.Create(QsTuple <QsTypeItem> .NewQsTupleItem(QsTypeItem.NewAnonymous(unit))));
var type = new QsCustomType(fullName: MakeFullName(access + "Type"),
attributes: ImmutableArray <QsDeclarationAttribute> .Empty,
modifiers: new Modifiers(access),
sourceFile: source,
location: ZeroLocation,
type: unit,
typeItems: typeItems,
documentation: ImmutableArray.Create <string>(),
comments: QsComments.Empty);
return(new[]
{
QsNamespaceElement.NewQsCallable(callable),
QsNamespaceElement.NewQsCustomType(type)
});
});
var emptyLookup = Array.Empty <ImmutableArray <string> >().ToLookup(x => NonNullable <string> .New(""));
var ns = new QsNamespace(CanonName, elements.ToImmutableArray(), emptyLookup);
var docNs = new DocNamespace(ns);
var stream = new MemoryStream();
docNs.WriteToStream(stream, null);
var expected = @"### YamlMime:QSharpNamespace
uid: microsoft.quantum.canon
name: Microsoft.Quantum.Canon
operations:
- uid: microsoft.quantum.canon.defaultaccessoperation
summary: ''
newtypes:
- uid: microsoft.quantum.canon.defaultaccesstype
summary: ''
...
";
var actual = Encoding.UTF8.GetString(stream.ToArray());
Assert.Equal(expected, actual);
}