ap0llo / mddocs Goto Github PK

View Code? Open in Web Editor NEW

28.0 28.0 4.0 1.9 MB

A tool to generate documentation as Markdown files

License: MIT License

C# 99.94% PowerShell 0.06%

api csharp documentation dotnet markdown

mddocs's People

Contributors

Stargazers

Watchers

Forkers

madelson friflo amir-tepper velopack

mddocs's Issues

Improve rendering of bool/switch commandline parameters

The usage for following options class

class Opts 
{
   [Option("parameter")]
   public bool MySwitch { get;set; } 
}

is currently rendered as

app.exe [--parameter <VALUE>}

However, the CommandLineParser library does not seem to accept a value in this case and just assumes bool properties are switch parameters (true is parameter is present, otherwise false).

To reflect this, bool paramters should be shown without the <VALUE> placeholder:

app.exe [--parameter]

Include default value in parameter details

If a method parameter has a default values, e.g.

public void MyMethod(string parameter = "value");

the default value is already included in the generated definition of the method.

However, this information is missing from the details section for the parameter.
It only includes the parameter's name and type as well as the description (if specified).

Action Required: Fix Renovate Configuration

There is an error with this repository's Renovate configuration that needs to be fixed. As a precaution, Renovate will stop PRs until it is resolved.

Error type: Cannot find preset's package (github>whitesource/merge-confidence:beta)

Include protected/protected internal members where appropriate

For types that are (1) not sealed and (2) have a visible constructor (public, protected, or protected internal), all protected/protected internal members are part of the public API.

Currently, it looks like we are filtering down to just public members.

Include list of exit codes in generated documentation

For commandline applications, the exit code is used to communicate errors. Some applications might use more detailed exit codes than 0 for success and 1 for error.

If different error codes are used to signal different results (e.g. different kinds or errors, warnings etc), it would be useful if the generated commandline help would list the exit codes and their meaning.

To get the list of possible exit codes, the option classes would have to be annotated with additioal attributes. Because the attribute is not included in the CommandLineParser package, it would need to ship as a MdDocs.* package (possibly as source package to avoid adding having to ship the annotations with the application.

The annotation could look something like this:

[Verb("command")]
[ExitCode(0, "The command completed successfully")]
[ExitCode(1, "The command completed with warnings")]
[ExitCode(2, "Invalid arguments")]
[ExitCode(3, "Unspecified error")]
class MyCommandOptions
{
    //...
}

For multi-command applications, the exit codes should be listed for every command as well as on the application main page (all exit codes of all commands)

Support for multiple assemblies

First of all, great tool. This paired with Docsify or MkDocs blows DocFX out of the water. One thing that Vsxmd and DocFX do support that I think is sorely missing here, is the ability to output the docs for multiple assemblies to the same path. For example, say you have a library that's broken into 3 or 4 parts because the others add to the original. With the current setup of this tool, it's not possible to output those docs to the same directory since the tool deletes anything in the folder upon initiation. Further complicating matters since this tool creates a folder structure that mimics the namespaces (not a bad thing), you would have to move folders around to create the desired layout. Not hard on my computer, but really difficult to account for during CI. An idea on what I'm talking about, let's say I have the folder structure shown below

docs/
- api/
- all the docs
- README.md
src/
- LibA
  - other files I don't feel like listing
  - LibA.csproj
- LibB
  - again, other files I don't feel like listing
  - LibB.csproj

Obviously, we'll assume LibA and LibB share a namespace, say RootNamespace, so we have RootNamespace.LibA and RootNamespace.LibB. Then I run dotnet mddocs apireference -a src/LibA/bin/Debug/net5.0/LibA.dll -o docs/api/ everything works as expected; but if I then do dotnet mddocs apireference -a src/LibB/bin/Debug/net5.0/LibB.dll -o docs/api/ everything in the api/ folder gets deleted first. That's smart for incremental building, so old APIs don't get left in the documentation, but it has the unintended side effect that multi-project libraries can't put their documentation together.

I do realize this is a very niche problem, but it's becoming a lot more common in the dotnet world to have a larger project broken into multiple smaller subprojects.

Command Line reference shows hidden commands

Actual behavior

For a hidden command, e.g.

[Verb("sample", Hidden = true)]
internal class SampleOptions

documentation is generated.

Expected behavior

Command is ignored because it is marked as hidden

Add support for <em> and <strong> tags

Visual Studio supports (or at least will support) more tags for formatting text in XML documentation comments (see https://twitter.com/mika_dumont/status/1232853061200035840):

c
see tag with href
bullet lists
numbered lists
em
strong

Most of the tags are already supported my MdDocs but em and stong are currently missing and should be added.

Support nullable reference types in API reference

When generating documentation for libraries that use C# 8's nullable reference types, the information if a value is nullable or not should be included in the documentation.

Add test for .NET SDK 5 to MdDocs.MSBuild.IntegrationTest

MdDocs.MSBuild.IntegrationTest verifies the MdDocs MSBuild tasks work on different versions of MSBuild and the .NET SDK.
(see MSBuildIntegrationTest.cs)

There should be a test case for the .NET 5 SDK

Support <exception /> tag for indexers and events

For indexers and events, the <exception /> tag is currently ignored.

Microsoft Docs states that

This tag can be applied to definitions for methods, properties, events, and indexers.

Exception info should thus be included in the documentation for indexers and events.

Boolean literals in definitions use wrong casing

Given the following type definition

[AttributeUsage(AttributeTargets.Property, AllowMultiple = false, Inherited = true)]
public sealed class MyCustomAttribute : Attribute
{ }

documentation for the type displays this definition:

[AttributeUsage(AttributeTargets.Property, AllowMultiple = False, Inherited = True)]
public sealed class MyCustomAttribute : Attribute

which uses True/False instead of true/false.

The definition should use the proper bool literals to make the definition valid C#

Show value of const fields in API documentation

For const fields, the value is known at compile-time.
If a types exposes a public const field, the constant value should be included in the API documentation.

MSBuild tasks fail with FileNotFoundException

Summary

The MSBuild task to generate documentation fails because Microsoft.Extensions.Configuration.Abstractions cannot be found.

Affected versions:

0.4.163

Stack Trace:

Microsoft (R) Build Engine version 16.5.0+d4cbfca49 for .NET Core
Copyright (C) Microsoft Corporation. All rights reserved.

  Restore completed in 39,79 ms for ~\source\repos\markdown-generator\src\MarkdownGenerator\Grynwald.MarkdownGenerator.csproj.
  Restore completed in 40,78 ms for ~\source\repos\markdown-generator\src\MarkdownGenerator.Test\Grynwald.MarkdownGenerator.Test.csproj.
  Restore completed in 40,81 ms for ~\source\repos\markdown-generator\src\MarkdownGenerator.Test.DocsVerification\Grynwald.MarkdownGenerator.Test.DocsVerification.csproj.
  Restore completed in 42,09 ms for ~\source\repos\markdown-generator\src\MarkdownGenerator.Test.ApiApproval\Grynwald.MarkdownGenerator.Test.ApiApproval.csproj.
  InheritDocTask replaced 0 of 0 inheritdoc tags and removed 0 non-public member docs in ~\source\repos\markdown-generator\Build\Debug\Grynwald.MarkdownGenerator\netstandard2.0\Grynwald.MarkdownGenerator.xml
  Grynwald.MarkdownGenerator -> ~\source\repos\markdown-generator\Build\Debug\Grynwald.MarkdownGenerator\netstandard2.0\Grynwald.MarkdownGenerator.dll
    error MSB4018: The "GenerateApiReferenceDocumentation" task failed unexpectedly. [~\source\repos\markdown-generator\src\MarkdownGenerator\Grynwald.MarkdownGenerator.csproj]
    error MSB4018: System.IO.FileNotFoundException: Could not load file or assembly 'Microsoft.Extensions.Configuration.Abstractions, Version=3.1.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60'. The system cannot find the file specified. [~\source\repos\markdown-generator\src\MarkdownGenerator\Grynwald.MarkdownGenerator.csproj]
    error MSB4018: File name: 'Microsoft.Extensions.Configuration.Abstractions, Version=3.1.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60' [~\source\repos\markdown-generator\src\MarkdownGenerator\Grynwald.MarkdownGenerator.csproj]
    error MSB4018:    at Grynwald.MdDocs.Common.Configuration.ConfigurationProvider.GetConfiguration[T](String sectionName) [~\source\repos\markdown-generator\src\MarkdownGenerator\Grynwald.MarkdownGenerator.csproj]
    error MSB4018:    at Grynwald.MdDocs.ApiReference.Configuration.ConfigurationProviderExtensions.GetApiReferenceConfiguration(ConfigurationProvider configurationLoader) [~\source\repos\markdown-generator\src\MarkdownGenerator\Grynwald.MarkdownGenerator.csproj]
    error MSB4018:    at Grynwald.MdDocs.MSBuild.GenerateApiReferenceDocumentation.Execute() in /_/src/MdDocs.MSBuild/src/GenerateApiReferenceDocumentation.cs:line 21 [~\source\repos\markdown-generator\src\MarkdownGenerator\Grynwald.MarkdownGenerator.csproj]
    error MSB4018:    at Microsoft.Build.BackEnd.TaskExecutionHost.Microsoft.Build.BackEnd.ITaskExecutionHost.Execute() [~\source\repos\markdown-generator\src\MarkdownGenerator\Grynwald.MarkdownGenerator.csproj]
    error MSB4018:    at Microsoft.Build.BackEnd.TaskBuilder.ExecuteInstantiatedTask(ITaskExecutionHost taskExecutionHost, TaskLoggingContext taskLoggingContext, TaskHost taskHost, ItemBucket bucket, TaskExecutionMode howToExecuteTask) [~\source\repos\markdown-generator\src\MarkdownGenerator\Grynwald.MarkdownGenerator.csproj]
    error MSB4018:  [~\source\repos\markdown-generator\src\MarkdownGenerator\Grynwald.MarkdownGenerator.csproj]
    error MSB4018:  [~\source\repos\markdown-generator\src\MarkdownGenerator\Grynwald.MarkdownGenerator.csproj]

Build FAILED.

Include version in API reference documentation

For generated commandline reference, the version of the application is already included in the documentation. It should also be included in API reference documentation.
Just like for commandline reference, there should be a --no-version commandline switch to prevent version from being included

Version with configuration not available?

https://github.com/ap0llo/mddocs/blob/master/docs/configuration/README.md states:

Applies to: Version 0.5 an later

However, I can't find anything newer than version 0.4.x on NuGet. Docs mistake or is this functionality not yet released?

Show return value attributes for methods

A method's return value can have attributes, e.g.

[return: MyAttribute]
public void MyMethod() 
{}

Return value attributes should be listed in the documentation and be included in the generated C# definition.

Related issue: #17

Intentional New Lines Removed From `<code>` Blocks

I have the following <code> blocks inside an <example> block :

/// <example>
///     The following example demonstrates how to create a <see cref="Sprite"/> using a
///     <see cref="MonoGame.Aseprite.Content.Processors.SpriteProcessor"/>.
///     <code>
///     //  Load an Aseprite file
///     AsepriteFile aseFile = AsepriteFile.Load("path-to-file");
///     
///     //  Use the SpriteProcessor to create a Sprite
///     Sprite sprite = SpriteProcessor.Process(GraphicsDevice, aseFile, frameIndex: 0);
///     </code>
///     
///     The following example demonstrates how to create a <see cref="Sprite"/> from a <see cref="TextureAtlas"/>.
///     <code>
///     //  Load an Aseprite File
///     AsepriteFile aseFile = AsepriteFile.Load("path-to-file")
///     
///     //  Create a TextureAtlas from the AsepriteFile using the TextureAtlasProcessor
///     TextureAtlas atlas = TextureAtlasProcessor.Process(GraphicsDevice, aseFile);
///     
///     //  Create a Sprite from region 0 in the TextureAtlas
///     Sprite sprite = atlas.CreateSprite(regionIndex: 0);
///     </code>
///     
///     The following example demonstrates how to create a <see cref="Sprite"/> from a <see cref="SpriteSheet"/>.
///     <code>
///     //  Load an Aseprite File
///     AsepriteFile aseFile = AsepriteFile.Load("path-to-file")
///     
///     //  Create a SpriteSheet from the AsepriteFile using the SpriteSheetProcessor
///     SpriteSheet spriteSheet = SpriteSheetProcessor.Process(GraphicsDevice, aseFile);
///     
///     //  Create a Sprite from region 0 in the SpriteSheet
///     Sprite sprite = spriteSheet.CreateSprite(regionIndex: 0);
///     </code>
/// </example>

when generated using mddocs it produces the following output

Notice that within the generated markdown code blocks, the intentional new lines added in the XML are stripped out. If possible, it would be preferred to have new lines within the <code>...</code> sections preserved for formatting.

NullReferenceException when running against .net 8 assembly

I am running the following against a .net 8 assembly:

mddocs apireference --assemblies "C:\Git\...\bin\Debug\net8.0\Assembly.dll" --outdir "C:\Git\....\docs"

Which results in the following exception being thrown:

INFORMATION - Reading XML documentation comments from 'C:\Git\...\bin\Debug\net8.0\Assembly.xml'
Unhandled exception. System.NullReferenceException: Object reference not set to an instance of an object.
   at Grynwald.MdDocs.Common.ParameterDefinitionExtensions.<>c.<GetCustomAttributes>b__0_0(CustomAttribute attribute) in /_/src/MdDocs.Common/_Extensions/_Cecil/ParameterDefinitionExtensions.cs:line 31
   at System.Linq.Utilities.<>c__DisplayClass1_0`1.<CombinePredicates>b__0(TSource x)
   at System.Linq.Enumerable.WhereEnumerableIterator`1.MoveNext()
   at Grynwald.MdDocs.ApiReference.Model.CSharpDefinitionFormatter.AppendCustomAttributes(StringBuilder definitionBuilder, IEnumerable`1 customAttributes, Boolean singleLine) in /_/src/MdDocs.ApiReference/Model/_Helpers/CSharpDefinitionFormatter.cs:line 362
   at Grynwald.MdDocs.ApiReference.Model.CSharpDefinitionFormatter.GetDefinition(ParameterDefinition parameter) in /_/src/MdDocs.ApiReference/Model/_Helpers/CSharpDefinitionFormatter.cs:line 747
   at System.Linq.Enumerable.SelectIListIterator`2.MoveNext()
   at System.Text.StringBuilder.AppendJoinCore[T](Char& separator, Int32 separatorLength, IEnumerable`1 values)
   at System.Text.StringBuilder.AppendJoin[T](String separator, IEnumerable`1 values)
   at Grynwald.MdDocs.ApiReference.Model.CSharpDefinitionFormatter.GetDefinition(MethodDefinition method) in /_/src/MdDocs.ApiReference/Model/_Helpers/CSharpDefinitionFormatter.cs:line 235
   at Grynwald.MdDocs.ApiReference.Model.MethodLikeOverloadDocumentation..ctor(MethodDefinition definition, IXmlDocsProvider xmlDocsProvider) in /_/src/MdDocs.ApiReference/Model/MethodLikeOverloadDocumentation.cs:line 64
   at Grynwald.MdDocs.ApiReference.Model.ConstructorOverloadDocumentation..ctor(ConstructorDocumentation methodDocumentation, MethodDefinition definition, IXmlDocsProvider xmlDocsProvider) in /_/src/MdDocs.ApiReference/Model/ConstructorOverloadDocumentation.cs:line 29
   at Grynwald.MdDocs.ApiReference.Model.ConstructorDocumentation.<>c__DisplayClass5_0.<.ctor>b__1(MethodDefinition d) in /_/src/MdDocs.ApiReference/Model/ConstructorDocumentation.cs:line 42
   at System.Linq.Enumerable.WhereSelectEnumerableIterator`2.MoveNext()
   at System.Linq.Enumerable.ToDictionary[TSource,TKey](IEnumerable`1 source, Func`2 keySelector, IEqualityComparer`1 comparer)
   at Grynwald.MdDocs.ApiReference.Model.ConstructorDocumentation..ctor(TypeDocumentation typeDocumentation, IEnumerable`1 definitions, IXmlDocsProvider xmlDocsProvider) in /_/src/MdDocs.ApiReference/Model/ConstructorDocumentation.cs:line 41
   at Grynwald.MdDocs.ApiReference.Model.TypeDocumentation..ctor(AssemblyDocumentation assemblyDocumentation, NamespaceDocumentation namespaceDocumentation, TypeDefinition definition, IXmlDocsProvider xmlDocsProvider, ILogger logger, TypeDocumentation declaringType) in /_/src/MdDocs.ApiReference/Model/TypeDocumentation.cs:line 237
   at Grynwald.MdDocs.ApiReference.Model.AssemblySetDocumentation.LoadTypeRecursively(AssemblyDocumentation assemblyDocumentation, IXmlDocsProvider xmlDocsProvider, TypeDefinition typeDefinition, TypeDocumentation declaringType) in /_/src/MdDocs.ApiReference/Model/AssemblySetDocumentation.cs:line 185
   at Grynwald.MdDocs.ApiReference.Model.AssemblySetDocumentation.LoadAssemblies(IReadOnlyList`1 assemblyDefinitions) in /_/src/MdDocs.ApiReference/Model/AssemblySetDocumentation.cs:line 170
   at Grynwald.MdDocs.ApiReference.Model.AssemblySetDocumentation..ctor(IReadOnlyList`1 assemblyDefinitions, IXmlDocsProvider xmlDocsProvider, ILogger logger) in /_/src/MdDocs.ApiReference/Model/AssemblySetDocumentation.cs:line 61
   at Grynwald.MdDocs.ApiReference.Model.AssemblySetDocumentation.FromAssemblyFiles(IEnumerable`1 filePaths, ILogger logger) in /_/src/MdDocs.ApiReference/Model/AssemblySetDocumentation.cs:line 116
   at Grynwald.MdDocs.ApiReference.Commands.ApiReferenceCommand.Execute() in /_/src/MdDocs.ApiReference/Commands/ApiReferenceCommand.cs:line 31
   at Grynwald.MdDocs.Program.OnApiReferenceCommand(ILogger logger, ApiReferenceOptions opts) in /_/src/MdDocs/Program.cs:line 59
   at Grynwald.MdDocs.Program.<>c.<Main>b__0_1(ApiReferenceOptions opts) in /_/src/MdDocs/Program.cs:line 31
   at CommandLine.ParserResultExtensions.MapResult[T1,T2,TResult](ParserResult`1 result, Func`2 parsedFunc1, Func`2 parsedFunc2, Func`2 notParsedFunc)
   at Grynwald.MdDocs.Program.Main(String[] args) in /_/src/MdDocs/Program.cs:line 28

The same extract runs properly against the same assembly when it is built with .net 6.

Show attributes for members

Documentation for types includes a list of the type's attributes.

This list is not shown for other members that can have attributes:

Constructors
Methods
- Method itself
- Parameters
- Return value
Fields
Properties
Indexers
Events

In the generated C# definition, all attributes are shown.

Related issue: #18

Include notice in generated files to indicate that files are auto-generated

When generated files are mixed with documents written by humans (e.g. markdown docs checked into a repository) it might be hard to differentiate between user- and machine-generated files.

To make that distinction easier, the generated files should include a notice at the top (as comment) to indicate the file was auto-generated.

System.NullReferenceException Error When Using apireference

I just tried your tool and am getting the error below. Is there something I'm doing wrong?

C:\src\GitHub\dotNetTips.Utility.Core\src>mddocs apireference --assembly C:\src\GitHub\dotNetTips.Utility.Core\appbin\netcoreapp2.2\dotNetTips.Utility.Standard.Extensions.dll --outdir c:\temp
INFORMATION: Using preset 'Default' for generating markdown
INFORMATION: Loading assembly from 'C:\src\GitHub\dotNetTips.Utility.Core\appbin\netcoreapp2.2\dotNetTips.Utility.Standard.Extensions.dll'
INFORMATION: Reading XML documentation comments from 'C:\src\GitHub\dotNetTips.Utility.Core\appbin\netcoreapp2.2\dotNetTips.Utility.Standard.Extensions.xml'
WARNING: Encountered unknown element 'count'. Element will be ignored.
WARNING: Encountered unknown element 'count'. Element will be ignored.
WARNING: Encountered unknown element 'count'. Element will be ignored.
WARNING: Encountered unknown element 'count'. Element will be ignored.
WARNING: Encountered unknown element 'count'. Element will be ignored.
Unhandled exception. System.NullReferenceException: Object reference not set to an instance of an object.
   at Grynwald.MdDocs.ApiReference.Model.CSharpDefinitionFormatter.GetLiteral(TypeReference typeReference, Object value) in D:\a\1\s\src\MdDocs.ApiReference.Model\_Helpers\CSharpDefinitionFormatter.cs:line 693
   at Grynwald.MdDocs.ApiReference.Model.CSharpDefinitionFormatter.GetDefinition(ParameterDefinition parameter) in D:\a\1\s\src\MdDocs.ApiReference.Model\_Helpers\CSharpDefinitionFormatter.cs:line 759
   at System.Linq.Enumerable.SelectIListIterator`2.MoveNext()
   at System.Text.StringBuilder.AppendJoinCore[T](Char* separator, Int32 separatorLength, IEnumerable`1 values)
   at System.Text.StringBuilder.AppendJoin[T](String separator, IEnumerable`1 values)
   at Grynwald.MdDocs.ApiReference.Model.CSharpDefinitionFormatter.GetDefinition(MethodDefinition method) in D:\a\1\s\src\MdDocs.ApiReference.Model\_Helpers\CSharpDefinitionFormatter.cs:line 234
   at Grynwald.MdDocs.ApiReference.Model.MethodLikeOverloadDocumentation..ctor(MethodDefinition definition, IXmlDocsProvider xmlDocsProvider) in D:\a\1\s\src\MdDocs.ApiReference.Model\MethodLikeOverloadDocumentation.cs:line 63
   at Grynwald.MdDocs.ApiReference.Model.MethodOverloadDocumentation..ctor(MethodDocumentation methodDocumentation, MethodDefinition definition, IXmlDocsProvider xmlDocsProvider) in D:\a\1\s\src\MdDocs.ApiReference.Model\MethodOverloadDocumentation.cs:line 25
   at Grynwald.MdDocs.ApiReference.Model.MethodDocumentation.<>c__DisplayClass7_0.<.ctor>b__1(MethodDefinition d) in D:\a\1\s\src\MdDocs.ApiReference.Model\MethodDocumentation.cs:line 42
   at System.Linq.Enumerable.SelectIListIterator`2.MoveNext()
   at System.Linq.Enumerable.ToDictionary[TSource,TKey](IEnumerable`1 source, Func`2 keySelector, IEqualityComparer`1 comparer)
   at System.Linq.Enumerable.ToDictionary[TSource,TKey](IEnumerable`1 source, Func`2 keySelector)
   at Grynwald.MdDocs.ApiReference.Model.MethodDocumentation..ctor(TypeDocumentation typeDocumentation, IEnumerable`1 definitions, IXmlDocsProvider xmlDocsProvider) in D:\a\1\s\src\MdDocs.ApiReference.Model\MethodDocumentation.cs:line 41
   at Grynwald.MdDocs.ApiReference.Model.TypeDocumentation.<>c__DisplayClass91_0.<.ctor>b__15(IGrouping`2 group) in D:\a\1\s\src\MdDocs.ApiReference.Model\TypeDocumentation.cs:line 242
   at System.Linq.Enumerable.SelectEnumerableIterator`2.MoveNext()
   at System.Linq.Enumerable.ToDictionary[TSource,TKey](IEnumerable`1 source, Func`2 keySelector, IEqualityComparer`1 comparer)
   at System.Linq.Enumerable.ToDictionary[TSource,TKey](IEnumerable`1 source, Func`2 keySelector)
   at Grynwald.MdDocs.ApiReference.Model.TypeDocumentation..ctor(ModuleDocumentation moduleDocumentation, NamespaceDocumentation namespaceDocumentation, TypeDefinition definition, IXmlDocsProvider xmlDocsProvider, ILogger logger, TypeDocumentation declaringType) in D:\a\1\s\src\MdDocs.ApiReference.Model\TypeDocumentation.cs:line 239
   at Grynwald.MdDocs.ApiReference.Model.ModuleDocumentation.LoadTypeRecursively(TypeDefinition typeDefinition, TypeDocumentation declaringType) in D:\a\1\s\src\MdDocs.ApiReference.Model\ModuleDocumentation.cs:line 119
   at Grynwald.MdDocs.ApiReference.Model.ModuleDocumentation..ctor(AssemblyDocumentation assemblyDocumentation, ModuleDefinition definition, IXmlDocsProvider xmlDocsProvider, ILogger logger) in D:\a\1\s\src\MdDocs.ApiReference.Model\ModuleDocumentation.cs:line 61
   at Grynwald.MdDocs.ApiReference.Model.AssemblyDocumentation..ctor(AssemblyDefinition definition, IXmlDocsProvider xmlDocsProvider, ILogger logger) in D:\a\1\s\src\MdDocs.ApiReference.Model\AssemblyDocumentation.cs:line 42
   at Grynwald.MdDocs.ApiReference.Model.AssemblyDocumentation.FromAssemblyFile(String filePath, ILogger logger) in D:\a\1\s\src\MdDocs.ApiReference.Model\AssemblyDocumentation.cs:line 83
   at Grynwald.MdDocs.Program.OnApiReferenceCommand(ILogger logger, ApiReferenceOptions opts) in D:\a\1\s\src\MdDocs\Program.cs:line 67
   at Grynwald.MdDocs.Program.<>c.<Main>b__0_1(ApiReferenceOptions opts) in D:\a\1\s\src\MdDocs\Program.cs:line 31
   at CommandLine.ParserResultExtensions.MapResult[T1,T2,TResult](ParserResult`1 result, Func`2 parsedFunc1, Func`2 parsedFunc2, Func`2 notParsedFunc)
   at Grynwald.MdDocs.Program.Main(String[] args) in D:\a\1\s\src\MdDocs\Program.cs:line 28

like this project - Well done!

Add support for `<inheritdoc/>`

The <inheritdoc/> element copies the documentation from a base class or interface if available. It would be very useful it it were supported by mddocs.

Mono.Cecil.AssemblyResolutionException

I could not find subj issue description anywhere. Placing my investigation here. I hope you will be able to find permanent solution.

All dependencies should be in the execution or bin folder ('.' or 'bin') according to Mono.Cecil assembly resolution logic.

                protected BaseAssemblyResolver()
                {
	                directories = new Collection<string>(2) { ".", "bin" };
                }

		public virtual AssemblyDefinition Resolve(AssemblyNameReference name, ReaderParameters parameters)
		{
			Mixin.CheckName(name);
			Mixin.CheckParameters(parameters);
			AssemblyDefinition assemblyDefinition = SearchDirectory(name, directories, parameters);
			if (assemblyDefinition != null)
			{
				return assemblyDefinition;
			}
			if (name.IsRetargetable)
			{
				name = new AssemblyNameReference(name.Name, Mixin.ZeroVersion)
				{
					PublicKeyToken = Empty<byte>.Array
				};
			}
			assemblyDefinition = SearchTrustedPlatformAssemblies(name, parameters);
			if (assemblyDefinition != null)
			{
				return assemblyDefinition;
			}
			if (this.ResolveFailure != null)
			{
				assemblyDefinition = this.ResolveFailure(this, name);
				if (assemblyDefinition != null)
				{
					return assemblyDefinition;
				}
			}
			throw new AssemblyResolutionException(name);
		}

		protected virtual AssemblyDefinition SearchDirectory(AssemblyNameReference name, global::System.Collections.Generic.IEnumerable<string> directories, ReaderParameters parameters)
		{
			string[] array = ((!name.IsWindowsRuntime) ? new string[2] { ".exe", ".dll" } : new string[2] { ".winmd", ".dll" });
			global::System.Collections.Generic.IEnumerator<string> enumerator = directories.GetEnumerator();
			try
			{
				while (((global::System.Collections.IEnumerator)enumerator).MoveNext())
				{
					string current = enumerator.get_Current();
					string[] array2 = array;
					foreach (string text in array2)
					{
						string text2 = Path.Combine(current, name.Name + text);
						if (File.Exists(text2))
						{
							try
							{
								return GetAssembly(text2, parameters);
							}
							catch (BadImageFormatException)
							{
							}
						}
					}
				}
			}
			finally
			{
				((global::System.IDisposable)enumerator)?.Dispose();
			}
			return null;
		}

There is workaround: build self-contained assembly (flag '-r').

Support pointing mddocs at a solution or project file

Would be really useful to be able to point the mddocs command line tool at a solution file or project file and have it build and then look up the executable instead of having to path to the built assembly.

Alternatively, the MSBuild tooling might eliminate the need for this if it could handle rendering multiple projects into the same root documentation folder.

Curious to hear your thoughts! Thanks!

feature request: support setting the index filename?

Thanks for the amazing tool.

In GitHub, README.md files in subfolders can also be automatically displayed without opening the file.

It seems the index filename has been fixed to index.md. Is there any chance to make it configurable?

Support for tuple element names

C# named tuples are currently not supported.

For example, the following method definition

void Method((string name, object value)[] parameters)

is shown in the documentation as

void Method([TupleElementNames(Mono.Cecil.CustomAttributeArgument[])]params ValueTuple<string, object>[] parameters);

The TupleElementNames attribute should not be included and the ValueTuple should be displayed in the native C# syntax, including element names.

Usage section shows Application Title instead of the executable name

The Usage section in the generated command line help uses the application name instead of the assembly/executable name.

Expected

myapp [--parameter1 <VALUE>]

Actual

My Application Name [--parameter1 <VALUE>]

Show tuples using native syntax

For a member that uses C# tuples e.g.

public (string, int) Method() 
{ }

the definition included in the documentation uses the generic syntax for ValueTuple:

public ValueTuple<string, int> Method();

In these cases, the C# tuple syntax (string, int) should be used.
When feasible, the definition should also include the tuple element names.