// Public Methods (3)
/// <summary>
/// Returns the documentation for a <see cref="Type" />.
/// </summary>
/// <param name="type">The CLR type.</param>
/// <param name="ignoreXmlDocErrors">
/// Ignore errors while loading XML documentation for <paramref name="type" /> or (re-)throw exception(s).
/// </param>
/// <returns>
/// The document for <paramref name="type" /> or <see langword="null" />
/// if <paramref name="type" /> is also <see langword="null" />.
/// </returns>
public static TypeDocumentation GetDocumentation(Type type,
bool ignoreXmlDocErrors = true)
{
if (type == null)
{
return(null);
}
var asm = type.Assembly;
if (asm == null)
{
return(null);
}
var asmDoc = AssemblyDocumentation.FromAssembly(asm,
ignoreXmlDocErrors: ignoreXmlDocErrors,
useCache: true);
var result = asmDoc.GetTypes()
.FirstOrDefault(t => TypeHelper.GetFullName(t.ClrType) == TypeHelper.GetFullName(type));
if (result == null)
{
result = new TypeDocumentation(asmDoc, type,
xml: null);
}
return(result);
}
public IDictionary <string, TypeDocumentation> GetModelDocumentation(HttpActionDescriptor actionDescriptor)
{
var retDictionary = new Dictionary <string, TypeDocumentation>();
ReflectedHttpActionDescriptor reflectedActionDescriptor = actionDescriptor as ReflectedHttpActionDescriptor;
if (reflectedActionDescriptor != null)
{
foreach (var parameterDescriptor in reflectedActionDescriptor.GetParameters())
{
var paramType = parameterDescriptor.ParameterType;
//if (!(paramType == typeof(QuizRequest)))
// continue;
if (!paramType.IsValueType)
{
TypeDocumentation typeDocs = new TypeDocumentation();
string selectExpression = String.Format(CultureInfo.InvariantCulture, TypeExpression, GetTypeName(paramType));
var typeNode = _documentNavigator.SelectSingleNode(selectExpression);
if (typeNode != null)
{
XPathNavigator summaryNode;
summaryNode = typeNode.SelectSingleNode("summary");
if (summaryNode != null)
{
typeDocs.Summary = summaryNode.Value;
}
}
foreach (var prop in paramType.GetProperties())
{
string propName = prop.Name;
string propDocs = string.Empty;
string propExpression = String.Format(CultureInfo.InvariantCulture, PropertyExpression, GetPropertyName(prop));
var propNode = _documentNavigator.SelectSingleNode(propExpression);
if (propNode != null)
{
XPathNavigator summaryNode;
summaryNode = propNode.SelectSingleNode("summary");
if (summaryNode != null)
{
propDocs = summaryNode.Value;
}
}
typeDocs.PropertyDocumentation.Add(new PropertyDocumentation(propName, prop.PropertyType.Name, propDocs));
}
retDictionary.Add(parameterDescriptor.ParameterName, typeDocs);
}
}
}
return(retDictionary);
}
public TypeDocumentationMarkdownWriter(IAssemblyDocumentationReader assemblyDocumentationReader, Type type)
{
if (assemblyDocumentationReader == null)
{
throw new ArgumentNullException(nameof(assemblyDocumentationReader));
}
_assemblyDocumentationReader = assemblyDocumentationReader;
_type = type;
_typeDocumentation = assemblyDocumentationReader.GetDocumentationOf(type);
_subWriters = new List <IMarkdownWriter>();
}
private void AddTables(TypeDocumentation type, MDDocument md)
{
var path = $"{this.rootName}/{type.FullName.Replace(".", "/")}";
this.AddTable("Constructors", $"{path}/Constructors", type.ConstructorDocumentations, md);
this.AddTable("Properties", $"{path}/Properties", type.PropertyDocumentations, md);
this.AddTable("Methods", $"{path}/Methods", type.MethodDocumentations, md);
this.AddTable("Fields", $"{path}/Fields", type.FieldDocumentations, md);
}
protected string GetTypeDirRelative(TypeDocumentation type)
{
var dirName = type.TypeId.Name;
if (type.TypeId is GenericTypeInstanceId genericTypeInstance)
{
dirName += "-" + genericTypeInstance.TypeArguments.Count;
}
else if (type.TypeId is GenericTypeId genericType)
{
dirName += "-" + genericType.Arity;
}
if (type.IsNestedType)
{
return(Path.Combine(GetTypeDirRelative(type.DeclaringType !), dirName));
}
else
{
return(Path.Combine(GetNamespaceDirRelative(type.NamespaceDocumentation), dirName));
}
}
/// <summary>
/// </summary>
protected override void OnParametersSet()
{
base.OnParametersSet();
this.Documentation = this.Parser.GetDocumentation(this.TypeName);
}
public PropertyDocBuilder(PropertyDocumentation propertyDocumentation, TypeDocumentation typeDocumentation, AssemblyDocumentation assemblyDocumentation)
: base(propertyDocumentation, typeDocumentation, assemblyDocumentation)
{
}
public MethodDocBuilder(MethodDocumentation methodDocumentation, TypeDocumentation typeDocumentation, AssemblyDocumentation assemblyDocumentation)
: base(methodDocumentation, typeDocumentation, assemblyDocumentation)
{
}
public TypeDocBuilder(TypeDocumentation typeDocumentation, AssemblyDocumentation assemblyDocumentation, string rootName)
: base(typeDocumentation, typeDocumentation, assemblyDocumentation)
{
this.rootName = rootName;
}
protected override OverloadDocumentation GetOverloadDocumentationInstance(TypeDocumentation typeDocumentation)
{
return(typeDocumentation.Operators.First().Overloads.First());
}
private async Task GenerateDocsAsync <TBuilder>(IEnumerable <DocumentationBase> documentations, TypeDocumentation typeDocumentation, AssemblyDocumentation assemblyDocumentation, DirectoryInfo typeDir, string dirName)
where TBuilder : DocBuilder
{
var docDir = Directory.CreateDirectory(Path.Combine(typeDir.FullName, dirName));
foreach (var documentation in documentations)
{
try
{
var docBuilder = (TBuilder)Activator.CreateInstance(typeof(TBuilder), documentation, typeDocumentation, assemblyDocumentation);
using (var stream = File.CreateText(Path.Combine(docDir.FullName, $"{documentation.GetSafeName()}.md")))
{
await stream.WriteAsync(docBuilder.Generate());
await stream.FlushAsync();
}
}
catch (System.IO.IOException)
{
// Failure to write.
}
}
}
protected abstract OverloadDocumentation GetOverloadDocumentationInstance(TypeDocumentation typeDocumentation);
protected override MemberDocumentation GetMemberDocumentationInstance(TypeDocumentation typeDocumentation)
{
return(typeDocumentation.Operators.First());
}
public FieldDocBuilder(FieldDocumentation fieldDocumentation, TypeDocumentation typeDocumentation, AssemblyDocumentation assemblyDocumentation)
: base(fieldDocumentation, typeDocumentation, assemblyDocumentation)
{
}
public DocBuilder(DocumentationBase documentation, TypeDocumentation typeDocumentation, AssemblyDocumentation assemblyDocumentation)
{
this.AssemblyDocumentation = assemblyDocumentation;
this.Documentation = documentation;
this.TypeDocumentation = typeDocumentation;
}
protected override MemberDocumentation GetMemberDocumentationInstance(TypeDocumentation typeDocumentation)
{
return(typeDocumentation.Constructors !);
}
protected override MemberDocumentation GetMemberDocumentationInstance(TypeDocumentation typeDocumentation)
{
return(typeDocumentation.Fields.Single());
}
protected abstract MemberDocumentation GetMemberDocumentationInstance(TypeDocumentation typeDocumentation);
