// 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 OverloadDocumentationTest()
{
var cs = @"
using System;
namespace Namespace1.Namespace2
{
public class Class1
{
public void Method1() => throw new NotImplementedException();
public static Class1 operator +(Class1 other) => throw new NotImplementedException();
public static Class1 operator +(Class1 left, Class1 right) => throw new NotImplementedException();
public static Class1 operator -(Class1 other) => throw new NotImplementedException();
public static Class1 operator -(Class1 left, Class1 right) => throw new NotImplementedException();
}
internal class InternalClass1
{ }
}
";
m_Assembly = Compile(cs);
using var assemblySetDocumentation = AssemblySetDocumentation.FromAssemblyDefinitions(m_Assembly);
m_AssemblyDocumentation = assemblySetDocumentation.Assemblies.Single();
}
private async Task OnExecuteAsync()
{
var dllPath = this.AssemblyPath;
var xmlPath = Path.Combine(Path.GetDirectoryName(this.AssemblyPath), $"{Path.GetFileNameWithoutExtension(this.AssemblyPath)}.xml");
var assemblyDocumentation = AssemblyDocumentation.Parse(dllPath, xmlPath);
var docs = Directory.CreateDirectory(this.DocumentPath);
foreach (var typeDocumentation in assemblyDocumentation.Types)
{
Console.WriteLine($"Generating docs for {typeDocumentation.FullName}...");
var rootDir = Directory.CreateDirectory(Path.Combine(docs.FullName, Path.Combine(typeDocumentation.Namespace.Split('.'))));
var typeDir = new DirectoryInfo(Path.Combine(rootDir.FullName, typeDocumentation.GetSafeName()));
if (typeDir.Exists)
{
typeDir.Delete(true);
}
typeDir.Create();
var typeDocBuilder = new TypeDocBuilder(typeDocumentation, assemblyDocumentation, docs.Name);
using (var stream = File.CreateText(Path.Combine(rootDir.FullName, $"{typeDocumentation.GetSafeName()}.md")))
{
try
{
await stream.WriteAsync(typeDocBuilder.Generate());
await stream.FlushAsync();
}
catch (System.IO.IOException)
{
// Failure to write.
}
}
// Constructors
var constructorsTask = this.GenerateDocsAsync <MethodDocBuilder>(typeDocumentation.ConstructorDocumentations, typeDocumentation, assemblyDocumentation, typeDir, "Constructors");
// Properties
var propertiesTask = this.GenerateDocsAsync <PropertyDocBuilder>(typeDocumentation.PropertyDocumentations, typeDocumentation, assemblyDocumentation, typeDir, "Properties");
// Methods
var methodsTask = this.GenerateDocsAsync <MethodDocBuilder>(typeDocumentation.MethodDocumentations, typeDocumentation, assemblyDocumentation, typeDir, "Methods");
// Fields
var fieldsTask = this.GenerateDocsAsync <FieldDocBuilder>(typeDocumentation.FieldDocumentations, typeDocumentation, assemblyDocumentation, typeDir, "Fields");
// Allow all the tasks to execute in parallel.
await Task.WhenAll(constructorsTask, propertiesTask, methodsTask, fieldsTask);
}
}
public MemberDocumentationTest()
{
var cs = @"
using System;
namespace Namespace1.Namespace2
{
public class Class1
{
public event EventHandler Event1;
public readonly Class1 Field1;
public int Property1 { get; set; }
public Class1()
{ }
public Class1(string parameter)
{ }
public void Method1() { }
public static Class1 operator +(Class1 other) => throw new NotImplementedException();
}
internal class InternalClass1
{ }
}
";
m_Assembly = Compile(cs);
m_AssemblyDocumentation = AssemblySetDocumentation.FromAssemblyDefinitions(m_Assembly)
.Assemblies
.Single();
}
public PropertyDocBuilder(PropertyDocumentation propertyDocumentation, TypeDocumentation typeDocumentation, AssemblyDocumentation assemblyDocumentation)
: base(propertyDocumentation, typeDocumentation, assemblyDocumentation)
{
}
public MethodDocBuilder(MethodDocumentation methodDocumentation, TypeDocumentation typeDocumentation, AssemblyDocumentation assemblyDocumentation)
: base(methodDocumentation, typeDocumentation, assemblyDocumentation)
{
}
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.
}
}
}
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;
}
private static int Main(string[] args)
{
try
{
var configFile = new FileInfo(Path.Combine(Environment.CurrentDirectory,
"config.ini"));
var ini = new IniFileConfigRepository(configFile);
foreach (var settings in DocumentationSettings.FromConfig(ini)
.Where(ds => ds.IsActive))
{
try
{
var site = new Site(settings.WikiUrl,
settings.Username, settings.Password.ToUnsecureString());
var doc = AssemblyDocumentation.FromFile(new FileInfo(settings.AssemblyFile));
doc.UpdateSettings(settings);
var asmPageName = doc.GetWikiPageName();
var asmPage = new Page(site, asmPageName);
asmPage.LoadWithMetadata();
asmPage.ResolveRedirect();
asmPage.text = doc.ToMediaWiki();
asmPage.Save();
}
catch (Exception ex)
{
GlobalConsole.Current
.InvokeForConsoleColor((c, state) => c.WriteLine(state.Exception),
new
{
Exception = ex.GetBaseException() ?? ex,
}, foreColor: ConsoleColor.Red
, bgColor: ConsoleColor.Black);
}
}
return(0);
}
catch (Exception ex)
{
GlobalConsole.Current
.InvokeForConsoleColor((c, state) => c.WriteLine(state.Exception),
new
{
Exception = ex.GetBaseException() ?? ex,
}, foreColor: ConsoleColor.Yellow
, bgColor: ConsoleColor.Red);
return(1);
}
finally
{
#if DEBUG
global::MarcelJoachimKloubert.CLRToolbox.IO.GlobalConsole.Current.WriteLine();
global::MarcelJoachimKloubert.CLRToolbox.IO.GlobalConsole.Current.WriteLine();
global::MarcelJoachimKloubert.CLRToolbox.IO.GlobalConsole.Current.WriteLine("===== ENTER ====");
global::MarcelJoachimKloubert.CLRToolbox.IO.GlobalConsole.Current.ReadLine();
#endif
}
}
public TypeDocBuilder(TypeDocumentation typeDocumentation, AssemblyDocumentation assemblyDocumentation, string rootName)
: base(typeDocumentation, typeDocumentation, assemblyDocumentation)
{
this.rootName = rootName;
}