ap0llo / mddocs Goto Github PK
View Code? Open in Web Editor NEWA tool to generate documentation as Markdown files
License: MIT License
A tool to generate documentation as Markdown files
License: MIT License
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]
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
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
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.
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.
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();
(string, int)
should be used.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.
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
--no-version
commandline switch to prevent version from being includedI 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').
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.
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.
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.
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).
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?
The MSBuild task to generate documentation fails because Microsoft.Extensions.Configuration.Abstractions
cannot be found.
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.
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
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.
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!
For a hidden command, e.g.
[Verb("sample", Hidden = true)]
internal class SampleOptions
documentation is generated.
Command is ignored because it is marked as hidden
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?
Documentation for types includes a list of the type's attributes.
This list is not shown for other members that can have attributes:
In the generated C# definition, all attributes are shown.
Related issue: #18
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)
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.
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#
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)
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.
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
em
strong
Most of the tags are already supported my MdDocs but em
and stong
are currently missing and should be added.
The Usage section in the generated command line help uses the application name instead of the assembly/executable name.
myapp [--parameter1 <VALUE>]
My Application Name [--parameter1 <VALUE>]
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.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.