public override void WriteDocumentation(DocumentationWriter writer)
{
writer.WriteHeader();
writer.WritePageTitle(Name, Type.Kind.ToString());
writer.Write(this, Documentation.GetSummary());
writer.WriteLine("```csharp");
writer.WriteLine(CodeAmbience.ConvertSymbol(Type));
writer.WriteLine("```");
// attribute
writer.WriteDocItems(TypeParameters, "#### Type parameters");
writer.WriteDocItems(Parameters, "#### Parameters");
if (InvokeMethod.ReturnType.Kind != TypeKind.Void)
{
writer.WriteLine("#### Returns");
writer.WriteLine(writer.GetTypeLink(InvokeMethod.ReturnType) + " ");
writer.Write(this, Documentation.GetReturns());
}
writer.Write("### Example", Documentation.GetExample(), this);
writer.Write("### Remarks", Documentation.GetRemarks(), this);
}
public override void WriteDocumentation(DocumentationWriter writer)
{
writer.WriteHeader();
writer.WritePageTitle(Name, "Namespace");
writer.Write(this, Documentation.GetSummary());
writer.Write("### Remarks", Documentation.GetRemarks(), this);
if (writer.NestedTypeVisibility == NestedTypeVisibility.Namespace ||
writer.NestedTypeVisibility == NestedTypeVisibility.Everywhere)
{
writer.WriteChildrenLink <ClassDocItem>("Classes");
writer.WriteChildrenLink <StructDocItem>("Structs");
writer.WriteChildrenLink <InterfaceDocItem>("Interfaces");
writer.WriteChildrenLink <EnumDocItem>("Enums");
writer.WriteChildrenLink <DelegateDocItem>("Delegates");
}
else
{
writer.WriteDirectChildrenLink <ClassDocItem>("Classes");
writer.WriteDirectChildrenLink <StructDocItem>("Structs");
writer.WriteDirectChildrenLink <InterfaceDocItem>("Interfaces");
writer.WriteDirectChildrenLink <EnumDocItem>("Enums");
writer.WriteDirectChildrenLink <DelegateDocItem>("Delegates");
}
}
public override void WriteDocumentation(DocumentationWriter writer)
{
writer.WriteHeader();
writer.WritePageTitle($"{Parent.Name}.{Name}", "Property");
writer.Write(this, Documentation.GetSummary());
writer.WriteLine("```csharp");
writer.WriteLine(CodeAmbience.ConvertSymbol(Property));
writer.WriteLine("```");
// attributes
writer.WriteDocItems(Parameters, "#### Parameters");
if (Property.ReturnType.Kind != TypeKind.Void)
{
writer.WriteLine("#### Property Value");
writer.WriteLine(writer.GetTypeLink(Property.ReturnType) + " ");
writer.Write(this, Documentation.GetValue());
}
writer.WriteExceptions(this);
writer.Write("### Example", Documentation.GetExample(), this);
writer.Write("### Remarks", Documentation.GetRemarks(), this);
}
public override void WriteDocumentation(DocumentationWriter writer)
{
writer.WriteHeader();
writer.WritePageTitle(Name, Type.Kind.ToString());
writer.Write(this, Documentation.GetSummary());
List <IType> interfaces = Type.DirectBaseTypes.Where(t => t.Kind == TypeKind.Interface && t.GetDefinition().Accessibility == Accessibility.Public).ToList();
writer.WriteLine("```csharp");
writer.Write(CodeAmbience.ConvertSymbol(Type));
IType baseType = Type.DirectBaseTypes.FirstOrDefault(t => t.Kind == TypeKind.Class && !t.IsKnownType(KnownTypeCode.Object) && !t.IsKnownType(KnownTypeCode.ValueType));
if (baseType != null)
{
writer.Write(" : ");
writer.Write(BaseTypeAmbience.ConvertType(baseType));
}
foreach (IType @interface in interfaces)
{
writer.WriteLine(baseType is null ? " :" : ",");
baseType = Type;
writer.Write(BaseTypeAmbience.ConvertType(@interface));
}
writer.Break();
writer.WriteLine("```");
if (Type.Kind == TypeKind.Class)
{
writer.Write("Inheritance ");
writer.Write(string.Join(" > ", Type.GetNonInterfaceBaseTypes().Select(t => writer.GetTypeLink(this, t))));
writer.WriteLine(" ");
if (interfaces.Count > 0)
{
writer.Break();
}
}
// attribute
if (interfaces.Count > 0)
{
writer.Write("Implements ");
writer.Write(string.Join(", ", interfaces.Select(t => writer.GetTypeLink(this, t))));
writer.WriteLine(" ");
}
writer.WriteDocItems(TypeParameters, "#### Type parameters");
writer.Write("### Example", Documentation.GetExample(), this);
writer.Write("### Remarks", Documentation.GetRemarks(), this);
writer.WriteDirectChildrenLink <ConstructorDocItem>("Constructors");
writer.WriteDirectChildrenLink <FieldDocItem>("Fields");
writer.WriteDirectChildrenLink <PropertyDocItem>("Properties");
writer.WriteDirectChildrenLink <MethodDocItem>("Methods");
writer.WriteDirectChildrenLink <EventDocItem>("Events");
writer.WriteDirectChildrenLink <OperatorDocItem>("Operators");
}
public override void WriteDocumentation(DocumentationWriter writer)
{
writer.WriteLinkTarget(this);
writer.WriteLine($"`{Name}` {Field.GetConstantValue()} ");
writer.Write(this, Documentation.GetSummary());
writer.Write("### Example", Documentation.GetExample(), this);
writer.Write("### Remarks", Documentation.GetRemarks(), this);
}
public override void WriteDocumentation(DocumentationWriter writer)
{
writer.WriteHeader();
writer.Write(this, Documentation.GetSummary());
writer.Write("### Remarks", Documentation.GetRemarks(), this);
writer.WriteChildrenLink <NamespaceDocItem>("Namespaces");
}
public override void WriteDocumentation(DocumentationWriter writer)
{
writer.WriteHeader();
writer.WritePageTitle(Name, "Namespace");
writer.Write(this, Documentation.GetSummary());
writer.Write("### Remarks", Documentation.GetRemarks(), this);
writer.WriteChildrenLink <ClassDocItem>("Classes");
writer.WriteChildrenLink <StructDocItem>("Structs");
writer.WriteChildrenLink <InterfaceDocItem>("Interfaces");
writer.WriteChildrenLink <EnumDocItem>("Enums");
writer.WriteChildrenLink <DelegateDocItem>("Delegates");
}
public override void WriteDocumentation(DocumentationWriter writer)
{
writer.WriteLinkTarget(this);
writer.WriteLine($"`{TypeParameter.Name}` ");
writer.Write(this, Documentation);
if (TypeParameter.TypeConstraints.Any(c => !c.Type.IsObjectOrValueType()))
{
writer.Break();
writer.Write("Constraints ");
writer.Write(string.Join(", ", TypeParameter.TypeConstraints.Select(c => c.Type).Where(t => !t.IsObjectOrValueType()).Select(writer.GetTypeLink)));
writer.WriteLine(" ");
}
}
public Task <int> Execute()
{
return(ConsoleTask.ExecuteAsync(this, async(console) =>
{
foreach (var file in GetMatchingFiles(InputFile))
{
console.Write("Generating doc for ");
console.WriteLine(file);
var metadata = PackageMetadataProvider.FromFile(file);
var outputPath = Output.Replace("*", CleanFileName(metadata.Title));
var writer = new DocumentationWriter();
var extension = Path.GetExtension(outputPath).ToUpperInvariant().TrimStart('.');
switch (extension)
{
case "PUML":
case "TXT":
writer.Format = DiagramFormat.PlantUml;
writer.Output = DocumentOutput.Diagram;
break;
case "SVG":
case "PNG":
writer.Format = (DiagramFormat)Enum.Parse(typeof(DiagramFormat), extension, true);
writer.Output = DocumentOutput.Diagram;
break;
case "MD":
writer.Format = DiagramFormat.PlantUml;
writer.Output = DocumentOutput.Markdown;
break;
}
try
{
using (var stream = File.OpenWrite(outputPath))
await writer.WriteAsync(metadata, stream);
}
catch (Exception ex)
{
console.WriteLine("Error documenting " + file);
console.WriteLine(ex.ToString());
}
}
}));
}
public override void WriteDocumentation(DocumentationWriter writer)
{
writer.WriteHeader();
writer.WritePageTitle($"{Parent.Name}.{Name}", "Field");
writer.Write(this, Documentation.GetSummary());
writer.WriteLine("```csharp");
writer.WriteLine(CodeAmbience.ConvertSymbol(Field));
writer.WriteLine("```");
// todo attributes
writer.WriteLine("#### Field Value");
writer.WriteLine($"{writer.GetTypeLink(Field.Type)} ");
writer.Write("### Example", Documentation.GetExample(), this);
writer.Write("### Remarks", Documentation.GetRemarks(), this);
}
public override void WriteDocumentation(DocumentationWriter writer)
{
writer.WriteHeader();
writer.WritePageTitle($"{Parent.Name}.{Name}", "Event");
writer.Write(this, Documentation.GetSummary());
writer.WriteLine("```csharp");
writer.WriteLine(CodeAmbience.ConvertSymbol(Event));
writer.WriteLine("```");
// attributes
writer.WriteLine("#### Event type");
writer.WriteLine(writer.GetTypeLink(this, Event.ReturnType));
writer.Write("### Example", Documentation.GetExample(), this);
writer.Write("### Remarks", Documentation.GetRemarks(), this);
}
public override void WriteDocumentation(DocumentationWriter writer)
{
writer.WriteHeader();
writer.WritePageTitle(Name, "Constructor");
writer.Write(this, Documentation.GetSummary());
writer.WriteLine("```csharp");
writer.WriteLine(CodeAmbience.ConvertSymbol(Method));
writer.WriteLine("```");
// attributes
writer.WriteDocItems(Parameters, "#### Parameters");
writer.WriteExceptions(this);
writer.Write("### Example", Documentation.GetExample(), this);
writer.Write("### Remarks", Documentation.GetRemarks(), this);
}
public override void WriteDocumentation(DocumentationWriter writer)
{
writer.WriteHeader();
writer.WritePageTitle(Name, Type.Kind.ToString());
writer.Write(this, Documentation.GetSummary());
writer.WriteLine("```csharp");
writer.Write(CodeAmbience.ConvertSymbol(Type));
IType enumType = Type.GetEnumUnderlyingType();
writer.WriteLine(enumType.IsKnownType(KnownTypeCode.Int32) ? string.Empty : $" : {enumType.FullName}");
writer.WriteLine("```");
// attribute
writer.WriteDocItems <EnumFieldDocItem>("### Fields");
writer.Write("### Example", Documentation.GetExample(), this);
writer.Write("### Remarks", Documentation.GetRemarks(), this);
}
public override void WriteDocumentation(DocumentationWriter writer)
{
writer.WriteLinkTarget(this);
writer.WriteLine($"`{Parameter.Name}` {writer.GetTypeLink(this, Parameter.Type)} ");
writer.Write(this, Documentation);
}
public override void WriteDocumentation(DocumentationWriter writer)
{
writer.WriteLinkTarget(this);
writer.WriteLine($"`{TypeParameter.Name}` ");
writer.Write(this, Documentation);
}
public abstract void WriteDocumentation(DocumentationWriter writer);
public override void WriteDocumentation(DocumentationWriter writer)
{
writer.WriteHeader();
writer.WritePageTitle(Name, Type.Kind.ToString());
writer.Write(this, Documentation.GetSummary());
List <IType> interfaces = Type.DirectBaseTypes.Where(t => t.Kind == TypeKind.Interface && t.GetDefinition().Accessibility == Accessibility.Public).ToList();
writer.WriteLine("```csharp");
writer.Write(CodeAmbience.ConvertSymbol(Type));
IType baseType = Type.DirectBaseTypes.FirstOrDefault(t => t.Kind == TypeKind.Class && !t.IsKnownType(KnownTypeCode.Object) && !t.IsKnownType(KnownTypeCode.ValueType));
if (baseType != null)
{
writer.Write(" : ");
writer.Write(BaseTypeAmbience.ConvertType(baseType));
}
foreach (IType @interface in interfaces)
{
writer.WriteLine(baseType is null ? " :" : ",");
baseType = Type;
writer.Write(BaseTypeAmbience.ConvertType(@interface));
}
writer.Break();
writer.WriteLine("```");
bool needBreak = false;
if (Type.Kind == TypeKind.Class)
{
writer.Write("Inheritance ");
writer.Write(string.Join(" 🡒 ", Type.GetNonInterfaceBaseTypes().Where(t => t != Type).Select(writer.GetTypeLink)));
writer.Write(" 🡒 ");
writer.Write(Name);
writer.WriteLine(" ");
needBreak = true;
}
List <TypeDocItem> derived = writer.KnownItems.OfType <TypeDocItem>().Where(i => i.Type.DirectBaseTypes.Select(t => t is ParameterizedType g ? g.GetDefinition() : t).Contains(Type)).OrderBy(i => i.FullName).ToList();
if (derived.Count > 0)
{
if (needBreak)
{
writer.Break();
}
writer.Write("Derived " + Environment.NewLine + "↳ ");
writer.Write(string.Join(" " + Environment.NewLine + "↳ ", derived.Select(t => writer.GetLink(t))));
writer.WriteLine(" ");
needBreak = true;
}
// attribute
if (interfaces.Count > 0)
{
if (needBreak)
{
writer.Break();
}
writer.Write("Implements ");
writer.Write(string.Join(", ", interfaces.Select(writer.GetTypeLink)));
writer.WriteLine(" ");
}
writer.WriteDocItems(TypeParameters, "#### Type parameters");
writer.Write("### Example", Documentation.GetExample(), this);
writer.Write("### Remarks", Documentation.GetRemarks(), this);
writer.WriteDirectChildrenLink <ConstructorDocItem>("Constructors");
writer.WriteDirectChildrenLink <FieldDocItem>("Fields");
writer.WriteDirectChildrenLink <PropertyDocItem>("Properties");
writer.WriteDirectChildrenLink <MethodDocItem>("Methods");
writer.WriteDirectChildrenLink <EventDocItem>("Events");
writer.WriteDirectChildrenLink <OperatorDocItem>("Operators");
if (writer.NestedTypeVisibility == NestedTypeVisibility.DeclaringType ||
writer.NestedTypeVisibility == NestedTypeVisibility.Everywhere)
{
writer.WriteDirectChildrenLink <ClassDocItem>("Classes");
writer.WriteDirectChildrenLink <StructDocItem>("Structs");
writer.WriteDirectChildrenLink <InterfaceDocItem>("Interfaces");
writer.WriteDirectChildrenLink <EnumDocItem>("Enums");
writer.WriteDirectChildrenLink <DelegateDocItem>("Delegates");
}
}
public static void WriteContentTo(this XElement element, DocumentationWriter writer, bool inlineOnly = false)
{
using (IEnumerator <XNode> en = element.Nodes().GetEnumerator())
{
if (en.MoveNext())
{
XNode node;
var isFirst = true;
bool isLast;
do
{
node = en.Current;
isLast = !en.MoveNext();
if (node is XText t)
{
string value = t.Value;
value = TextUtility.RemoveLeadingTrailingNewLine(value, isFirst, isLast);
if (inlineOnly)
{
value = TextUtility.ToSingleLine(value);
}
writer.WriteString(value);
}
else if (node is XElement e)
{
switch (XmlTagMapper.GetTagOrDefault(e.Name.LocalName))
{
case XmlTag.C:
{
string value = e.Value;
value = TextUtility.ToSingleLine(value);
writer.WriteInlineCode(value);
break;
}
case XmlTag.Code:
{
if (inlineOnly)
{
break;
}
string value = e.Value;
value = TextUtility.RemoveLeadingTrailingNewLine(value);
writer.WriteCodeBlock(value);
break;
}
case XmlTag.List:
{
if (inlineOnly)
{
break;
}
string type = e.Attribute("type")?.Value;
if (!string.IsNullOrEmpty(type))
{
switch (type)
{
case "bullet":
{
WriteList(writer, e.Elements());
break;
}
case "number":
{
WriteList(writer, e.Elements(), isOrdered: true);
break;
}
case "table":
{
WriteTable(writer, e.Elements());
break;
}
default:
{
Debug.Fail(type);
break;
}
}
}
break;
}
case XmlTag.Para:
{
writer.WriteLine();
writer.WriteLine();
WriteContentTo(e, writer);
writer.WriteLine();
writer.WriteLine();
break;
}
case XmlTag.ParamRef:
{
string parameterName = e.Attribute("name")?.Value;
if (parameterName != null)
{
writer.WriteBold(parameterName);
}
break;
}
case XmlTag.See:
{
string commentId = e.Attribute("cref")?.Value;
if (commentId != null)
{
ISymbol symbol = writer.DocumentationModel.GetFirstSymbolForDeclarationId(commentId);
//XTODO: repair roslyn documentation
Debug.Assert(
symbol != null ||
commentId == "T:Microsoft.CodeAnalysis.CSharp.SyntaxNode" ||
commentId == "T:Microsoft.CodeAnalysis.CSharp.SyntaxToken" ||
commentId == "T:Microsoft.CodeAnalysis.CSharp.SyntaxTrivia" ||
commentId == "T:Microsoft.CodeAnalysis.VisualBasic.SyntaxNode" ||
commentId == "T:Microsoft.CodeAnalysis.VisualBasic.SyntaxToken" ||
commentId == "T:Microsoft.CodeAnalysis.VisualBasic.SyntaxTrivia",
commentId);
if (symbol != null)
{
writer.WriteLink(symbol, TypeSymbolDisplayFormats.Name_ContainingTypes_TypeParameters, SymbolDisplayAdditionalMemberOptions.UseItemPropertyName | SymbolDisplayAdditionalMemberOptions.UseOperatorName);
}
else
{
writer.WriteBold(TextUtility.RemovePrefixFromDocumentationCommentId(commentId));
}
}
break;
}
case XmlTag.TypeParamRef:
{
string typeParameterName = e.Attribute("name")?.Value;
if (typeParameterName != null)
{
writer.WriteBold(typeParameterName);
}
break;
}
case XmlTag.Example:
case XmlTag.Exception:
case XmlTag.Exclude:
case XmlTag.Include:
case XmlTag.InheritDoc:
case XmlTag.Param:
case XmlTag.Permission:
case XmlTag.Remarks:
case XmlTag.Returns:
case XmlTag.SeeAlso:
case XmlTag.Summary:
case XmlTag.TypeParam:
case XmlTag.Value:
{
break;
}
default:
{
Debug.Fail(e.Name.LocalName);
break;
}
}
}
else
{
Debug.Fail(node.NodeType.ToString());
}
isFirst = false;
} while (!isLast);
}
}
}
private static void WriteTable(DocumentationWriter writer, IEnumerable <XElement> elements)
{
using (IEnumerator <XElement> en = elements.GetEnumerator())
{
if (en.MoveNext())
{
XElement element = en.Current;
string name = element.Name.LocalName;
if (name == "listheader" &&
en.MoveNext())
{
int columnCount = element.Elements().Count();
writer.WriteStartTable(columnCount);
writer.WriteStartTableRow();
foreach (XElement element2 in element.Elements())
{
writer.WriteStartTableCell();
WriteContentTo(element2, writer, inlineOnly: true);
writer.WriteEndTableCell();
}
writer.WriteEndTableRow();
writer.WriteTableHeaderSeparator();
do
{
element = en.Current;
writer.WriteStartTableRow();
int count = 0;
foreach (XElement element2 in element.Elements())
{
writer.WriteStartTableCell();
WriteContentTo(element2, writer, inlineOnly: true);
writer.WriteEndTableCell();
count++;
if (count == columnCount)
{
break;
}
}
while (count < columnCount)
{
writer.WriteTableCell(null);
count++;
}
writer.WriteEndTableRow();
} while (en.MoveNext());
writer.WriteEndTable();
}
}
}
}
private static void WriteList(DocumentationWriter writer, IEnumerable <XElement> elements, bool isOrdered = false)
{
int number = 1;
using (IEnumerator <XElement> en = Iterator().GetEnumerator())
{
if (en.MoveNext())
{
if (isOrdered)
{
writer.WriteStartOrderedList();
}
else
{
writer.WriteStartBulletList();
}
do
{
WriteStartItem();
WriteContentTo(en.Current, writer, inlineOnly: true);
WriteEndItem();
} while (en.MoveNext());
if (isOrdered)
{
writer.WriteEndOrderedList();
}
else
{
writer.WriteEndBulletList();
}
}
}
IEnumerable <XElement> Iterator()
{
foreach (XElement element in elements)
{
if (element.Name.LocalName == "item")
{
using (IEnumerator <XElement> en = element.Elements().GetEnumerator())
{
if (en.MoveNext())
{
XElement element2 = en.Current;
if (element2.Name.LocalName == "description")
{
yield return(element2);
}
}
else
{
yield return(element);
}
}
}
}
}
void WriteStartItem()
{
if (isOrdered)
{
writer.WriteStartOrderedItem(number);
number++;
}
else
{
writer.WriteStartBulletItem();
}
}
void WriteEndItem()
{
if (isOrdered)
{
writer.WriteEndOrderedItem();
}
else
{
writer.WriteEndBulletItem();
}
}
}
