loxsmoke / mddox Goto Github PK

I'm trying to document a winmd file (a UWP WinRT component) but mddox can't seem to load it:

> mddox TreeDumpLibrary.winmd

Error: Could not load file or assembly 'TreeDumpLibrary, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null, ContentType=WindowsRuntime'.
   at System.Runtime.Loader.AssemblyLoadContext.LoadFromPath(IntPtr ptrNativeAssemblyLoadContext, String ilPath, String niPath, ObjectHandleOnStack retAssembly)
   at System.Runtime.Loader.AssemblyLoadContext.LoadFromAssemblyPath(String assemblyPath)
   at System.Reflection.Assembly.LoadFile(String path)
   at MdDox.Program.Main(String[] args) in C:\Dev\mddox\src\Program.cs:line 194

Hi,

thanks for a super cool tool!

One thing that would be helpful would be a command-line switch that tells mddox to ignore types that have no comments.

Would that be hard to do?

Thanks,
MR

PS D:\Git\_Bars\OBP.Core.Attributes> mddox .\bin\Release\netstandard2.0\OBP.Core.Attributes.dll -o TestAutoDoc.md -f github -s latest -n
Error: Unable to load one or more of the requested types.
Could not load file or assembly 'OBP.Core.Types.Annotations, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null'. Не удается найти указанный файл.
Could not load file or assembly 'OBP.Core.Types.Annotations, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null'. Не удается найти указанный файл.
Could not load file or assembly 'OBP.Core.Types.Annotations, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null'. Не удается найти указанный файл.
   at System.Reflection.RuntimeModule.GetTypes(RuntimeModule module)
   at System.Reflection.RuntimeModule.GetTypes()
   at System.Reflection.Assembly.GetTypes()
   at LoxSmoke.DocXml.Reflection.TypeCollection.GetReferencedTypes(Assembly assembly, ReflectionSettings settings)
   at LoxSmoke.DocXml.Reflection.TypeCollection.ForReferencedTypes(Assembly assembly, ReflectionSettings settings)
   at MdDox.OrderedTypeList.LoadTypes(Type rootType, Assembly assembly, Boolean recursiveAssemblyTraversal, List`1 recursiveAssemblies, List`1 ignoreAttributes, Boolean ignoreMethods, Boolean verbose) in C:\dev\mddox\src\OrderedTypeList.cs:line 66
   at MdDox.Program.Main(String[] args) in C:\dev\mddox\src\Program.cs:line 126

my code works with my own (non-public) nuget lib OBP.Core.Types.Annotations.
mddox crashes on it

Steps to reproduce

Assume a PowerShell session.

I installed the morelinq package using:

nuget install morelinq

The installation of the package succeeded with NuGet printing:

Feeds used:
  https://api.nuget.org/v3/index.json
  C:\Program Files (x86)\Microsoft SDKs\NuGetPackages\

Installing package 'morelinq' to 'T:\'.
  CACHE https://api.nuget.org/v3/registration3-gz-semver2/morelinq/index.json


Attempting to gather dependency information for package 'morelinq.3.2.0' with respect to project 'T:\', targeting 'Any,Version=v0.0'
Gathering dependency information took 43.8 ms
Attempting to resolve dependencies for package 'morelinq.3.2.0' with DependencyBehavior 'Lowest'
Resolving dependency information took 0 ms
Resolving actions to install package 'morelinq.3.2.0'
Resolved actions to install package 'morelinq.3.2.0'
Retrieving package 'morelinq 3.2.0' from 'nuget.org'.
Found package 'System.ValueTuple 4.4.0' in 'T:\'.
Package 'System.ValueTuple.4.4.0' already exists in folder 'T:\'
Successfully installed 'System.ValueTuple 4.4.0' to T:\
Adding package 'morelinq.3.2.0' to folder 'T:\'
Added package 'morelinq.3.2.0' to folder 'T:\'
Successfully installed 'morelinq 3.2.0' to T:\
Executing nuget actions took 204.68 ms

Then I listed the assemblies in the packages, using:

dir -Recurse -File morelinq.3.2.0\*.dll | select -ExpandProperty FullName

The output was:

T:\morelinq.3.2.0\lib\net451\MoreLinq.dll
T:\morelinq.3.2.0\lib\netstandard1.0\MoreLinq.dll
T:\morelinq.3.2.0\lib\netstandard2.0\MoreLinq.dll

I then executed the following to generate documentation:

mddox morelinq.3.2.0\lib\netstandard2.0\MoreLinq.dll

The tool failed with the following error message:

Error: Length cannot be less than zero.
Parameter name: length
   at System.String.Substring(Int32 startIndex, Int32 length)
   at DocXml.Reflection.ReflectionExtensions.ToNameString(Type type, Queue`1 tupleFieldNames, Func`3 typeNameConverter)
   at MdDox.DocumentationGenerator.DocumentClass(TypeInformation typeData) in C:\Dev\mddox\src\DocumentationGenerator.cs:line 306
   at MdDox.DocumentationGenerator.DocumentTypes() in C:\Dev\mddox\src\DocumentationGenerator.cs:line 349
   at MdDox.DocumentationGenerator.GenerateMarkdown(Type rootType, Assembly assembly, Boolean recursiveAssemblyTraversal, List`1 recursiveAssemblies, List`1 ignoreAttributes, Boolean ignoreMethods, IMarkdownWriter markdownWriter, String outputFileName) in C:\Dev\mddox\src\DocumentationGenerator.cs:line 127
   at MdDox.Program.Main(String[] args) in C:\Dev\mddox\src\Program.cs:line 193

More information

Running just mddox, which displays the usage, shows I am on version 0.2.0.0:

T:\> mddox
mddox, version 0.2.0.0, (c) 2019 loxsmoke
Markdown documentation generator. See https://github.com/loxsmoke/mddox for more info.

Usage:
   mddox <assembly> <optional-parameters>
   <assembly>             The name of the assembly to document.

Optional parameters:
   --output <output_md>   The name of the markdown output file.
   --format <format>      The markdown file format. Valid values: github,bitbucket.
   --recursive            Step into referenced assemblies recursively.
   --recursive <assembly> Step recursivelly only into specified assembly or assemblies.
   --ignore-methods       Do not generate documentation for methods and constructors.
   --ignore-attribute <name>
                          Do not generate documentation for properties with specified custom attribute.
                          For example JsonIgnoreAttribute
   --type <name>          Document specified only this and referenced types.

Hi,

I'm trying to create md documentation file, but I can't see my summary comment info in the markdown file. Here is an example:

• 0.5.1 version of the tool
• DLL generated by taken from published folder generated by dotnet publish -f netstandard2.1 -o published

Is there any way to have the tool also write out examples (using the <example> tag)?

When mddox generates heading with method name, the heading will contain internal hyperlinks within file itself (and with -s argument it will link to MSDN for common system types), which is just fine.

However it seems that the same algorithm is used for generating the table of methods, which leads to links within links, which is obviously not valid Markdown.

Hi,

take the following comment (on an interface):

/// <summary>
///     Implement this interface and pass it to one of the Create methods in <see cref="ParserFactory" />
///     if you want to customize how the types of parameters are formatted in help texts.
///     Refer to <see cref="DefaultTypeFormatter" /> as an example for how to implement this interface.
/// </summary>
public interface ITypeFormatter

The markdown generated for this is:

 Implement this interface and pass it to one of the Create methods in <see cref="T:ModernRonin.FluentArgumentParser.ParserFactory" />
    if you want to customize how the types of parameters are formatted in help texts.
    Refer to <see cref="T:ModernRonin.FluentArgumentParser.Extensibility.DefaultTypeFormatter" /> as an example for how to implement this interface.

Note how the crefs are not converted to links.

Cheers,
MR

Currently this comment text

<see href="https://en.wikipedia.org/wiki/Stuff">Stuff</see>

is converted to the following markdown

\<see href="https://en.wikipedia.org/wiki/Stuff"\>Stuff\</see\>

Expected markdown is this: [Stuff](https://en.wikipedia.org/wiki/Stuff)

Can you also export the -tags of the XML-documentation into the markdown-document?

The parameter type list is duplicated in the documentation of return values and function parameters.
For example return List<T> is documented as List<T><T>. The same thing happens for parameters that have generic types.

The current version of DocXml is missing loxsmoke/DocXml@f899b82 that fixes an exception when an enum has UInt32 as underlying type

I can't get mddox to generate markdown from my XML docs.

I installed it as a global tool and run it inside my project directory, but when I feed it my assembly it crashes with the following error:

D:\DEV\dtmf-detection\src\DtmfDetection.NAudio
❯ mddox .\bin\Debug\netstandard2.1\DtmfDetection.NAudio.dll
Error: Unable to load one or more of the requested types.
Could not load file or assembly 'netstandard, Version=2.1.0.0, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51'. The system cannot find the file specified.
Could not load file or assembly 'netstandard, Version=2.1.0.0, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51'. The system cannot find the file specified.
Could not load file or assembly 'netstandard, Version=2.1.0.0, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51'. The system cannot find the file specified.
Could not load file or assembly 'netstandard, Version=2.1.0.0, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51'. The system cannot find the file specified.
Could not load file or assembly 'netstandard, Version=2.1.0.0, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51'. The system cannot find the file specified.
Could not load file or assembly 'netstandard, Version=2.1.0.0, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51'. The system cannot find the file specified.
Could not load file or assembly 'netstandard, Version=2.1.0.0, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51'. The system cannot find the file specified.
Could not load file or assembly 'netstandard, Version=2.1.0.0, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51'. The system cannot find the file specified.
Could not load file or assembly 'netstandard, Version=2.1.0.0, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51'. The system cannot find the file specified.
Could not load file or assembly 'netstandard, Version=2.1.0.0, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51'. The system cannot find the file specified.
Could not load file or assembly 'netstandard, Version=2.1.0.0, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51'. The system cannot find the file specified.
Could not load file or assembly 'netstandard, Version=2.1.0.0, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51'. The system cannot find the file specified.
at System.Reflection.RuntimeModule.GetTypes(RuntimeModule module)
at System.Reflection.RuntimeModule.GetTypes()
at System.Reflection.Assembly.GetTypes()
at LoxSmoke.DocXml.Reflection.TypeCollection.GetReferencedTypes(Assembly assembly, ReflectionSettings settings)
at MdDox.DocumentationGenerator.GenerateMarkdown(Type rootType, Assembly assembly, Boolean recursiveAssemblyTraversal, List1 recursiveAssemblies, List1 ignoreAttributes, Boolean ignoreMethods, Boolean msdnLinks, String msdnView, Boolean showDateLine, IMarkdownWriter markdownWriter, String outputFileName) in C:\Dev\mddox\src\DocumentationGenerator.cs:line 151
at MdDox.Program.Main(String[] args) in C:\Dev\mddox\src\Program.cs:line 208

I noticed that mddox is a netcoreapp2.1, but my library is netstandard2.1. So I cloned this repo, changed the mddox project to netcoreapp3.1, built and ran it again from the output directory:

D:\DEV\mddox\src\bin\Debug\netcoreapp3.1
❯ dotnet .\mddox.dll ..\..\..\..\..\dtmf-detection\src\DtmfDetection.NAudio\bin\Debug\netstandard2.1\DtmfDetection.NAudio.dll
Error: Unable to load one or more of the requested types.
Could not load file or assembly 'NAudio, Version=1.10.0.0, Culture=neutral, PublicKeyToken=null'. The system cannot find the file specified.
at System.Reflection.RuntimeModule.GetTypes(RuntimeModule module)
at System.Reflection.RuntimeModule.GetTypes()
at System.Reflection.Assembly.GetTypes()
at LoxSmoke.DocXml.Reflection.TypeCollection.GetReferencedTypes(Assembly assembly, ReflectionSettings settings)
at LoxSmoke.DocXml.Reflection.TypeCollection.ForReferencedTypes(Assembly assembly, ReflectionSettings settings)
at MdDox.DocumentationGenerator.GenerateMarkdown(Type rootType, Assembly assembly, Boolean recursiveAssemblyTraversal, List1 recursiveAssemblies, List1 ignoreAttributes, Boolean ignoreMethods, Boolean msdnLinks, String msdnView, Boolean showDateLine, IMarkdownWriter markdownWriter, String outputFileName) in D:\DEV\mddox\src\DocumentationGenerator.cs:line 151
at MdDox.Program.Main(String[] args) in D:\DEV\mddox\src\Program.cs:line 208

As you can see, it still crashes, but with a slightly different exception. Now it's NAudio.dll mddox cannot find and that's from a nuget package my library is using.

Switching the project back to netcoreapp2.1 leads to the first exception where netstandard2.1 cannot be found.

So it's two problems: mddox needs to be upgraded to netcoreapp3.1 and somehow it needs to find dlls of a referenced package?

using System;
using System.Linq;
using System.Text;
using System.Text.RegularExpressions;
using MdDox.MarkdownWriters.Interfaces;

namespace MdDox.MarkdownWriters
{
public class AzureMarkdownWriter : IMarkdownWriter
{
public string FormatName => "azure";

    #region Basic writing
    public StringBuilder allText = new StringBuilder();

    public void Write(string text)
    {
        if (text == null) return;
        allText.AppendLine(text);
    }

    public void WriteLine(string text)
    {
        if (text != null) allText.AppendLine(text);
        allText.AppendLine();
    }
    #endregion

    #region Formatted writing
    public void WriteH1(string text)
    {
        WriteLine("# " + EscapeSpecialChars(text));
    }
    public void WriteH2(string text)
    {
        WriteLine("## " + EscapeSpecialChars(text));
    }

    public void WriteH3(string text)
    {
        WriteLine("### " + EscapeSpecialChars(text));
    }

    public void WriteLink(string anchorName, string text)
    {
        allText.Append(Link(anchorName, text));
    }
    public void WriteHeadingLink(string text)
    {
        allText.Append(HeadingLink(text));
    }
    public void WriteAnchor(string anchorName)
    {
        allText.Append($"<a name=\"{anchorName}\"></a>");
    }
    public void WriteHorizontalRule()
    {
        allText.AppendLine();
        WriteLine("---");
    }
    #endregion

    #region Tables
    public void WriteTableTitle(params string[] tableHeadings)
    {
        Write("| " + string.Join(" | ", tableHeadings) + " |");
        Write("|" + string.Join("|", tableHeadings.Select(x => "---")) + "|");
    }

    public void WriteTableRow(params string[] texts)
    {
        Write("| " + string.Join(" | ", texts.Select(EscapeSpecialText)) + " |");
    }
    #endregion

    #region Text formatting
    string EscapeSpecialText(string text)
    {
        if (text == null) return "";
        text = ResolveTag(text, "paramref", "name");
        return EscapeSpecialChars(text);
    }

    string ResolveTag(string text, string tagName, string attributeName)
    {
        var regex = new Regex("<" + tagName + "( +)" + attributeName + "( *)=( *)\"(.*?)\"( *)/>");
        for (; ; )
        {
            var match = regex.Match(text);
            if (!match.Success) return text;

            var attributeValue = match.Groups[4].Value;
            text = text.Substring(0, match.Index) + Bold(attributeValue) + text.Substring(match.Index + match.Length);
        }
    }

    public string EscapeSpecialChars(string text)
    {
        if (text == null) return "";
        text = text.Replace("<", "\\<");
        text = text.Replace(">", "\\>");
        text = text.Replace("&gt;", ">");
        text = text.Replace("&lt;", "<");
        text = text.Replace("|", "\\|");
        return text.Replace(Environment.NewLine, "<br>");
    }
    public string Bold(string text)
    {
        return "**" + text + "**";
    }
    public string Link(string anchorName, string text)
    {
        return $"[{text}]({anchorName})";
    }
    public string HeadingLink(string anchorName, string text = null)
    {
        anchorName = anchorName.ToLower();
        anchorName = anchorName.Replace("<", "%5C%3C");
        anchorName = anchorName.Replace(">", "%5C%3E");
        anchorName = anchorName.Replace(",", "%2C");
        anchorName = anchorName.RegexReplace(@"[^a-zA-Z\d\(\)\% -]", "").Replace(" ", "-");
        return $"[{text ?? anchorName}](#{anchorName})";
    }
    #endregion

    public string FullText => allText.ToString();
}

}

Currently documentation is generated for constructs that are not part of public API (internal classes, private members), which can lead to much confusion.

There is no switch to ignore non-public members. Although I would expect that non-public members would be hidden from docs by default and if needed, have to be explicitly enabled.

It would be good to have an optional parameter to exclude internal classes and methods from the generated documentation. Or maybe this is already possible?