First of all, I wanted to thank you for adding to the Cake community by adding this addin.

I was just wondering if you had seen this blog post:

http://cakebuild.net/blog/2016/08/cake-contribution-organization

We are currently going through a process of increasing the visibility of addins, and also trying to ensure their long term maintainability.

To that end, we are asking addin creators to add the cake-contrib user on NuGet as a co-owner (this can be done through the NuGet website by clicking on Manage Owners on the package page).

Would you be interested in doing this? If you have any questions about this, please let me know. There was some initial concern that the Cake Team were trying to "take over" packages, and that couldn't be further from the truth, and if you have this concern, or others, I would like to address them.

Thanks!

I am using this utility to generate .md files for RecyclableMemoryStream. I would expect newlines to be inserted where there are newlines in the original XML documentation. Am I doing something wrong? For example, see the class comments for RecyclableMemoryStream, which are lengthy. But the generated file is just a long string.

The script I'm using to generate it is here.

Create issues for problems found here: https://github.com/Faithlife/FaithlifeUtility/blob/master/docs/Faithlife.Utility.md

I'm trying to use XmlDocMarkdown with a Hugo site (defined here: https://github.com/mysql-net/MySqlConnector/tree/master/docs)

So far, I've gotten the best results with this command line:

xmldocmd --front-matter .\docs\front-matter.yml --clean --namespace-pages --permalink pretty .\src\MySqlConnector\bin\Release\netcoreapp3.0\MySqlConnector.dll docs\content\api\MySqlConnector\

However, the links in the generated files aren't correct, as they assume that the page will be served from /api/MySqlConnector/MySqlConnectorAssembly.html instead of /api/MySqlConnector/MySqlConnectorAssembly/. Thus, a relative link goes to /api/MySqlConnector/MySqlConnectorAssembly/MySql.Data.MySqlClient/MySqlConnectionType (which 404s) when it should be /api/MySqlConnector/MySql.Data.MySqlClient/MySqlConnectionType/.

I've fixed the generated links in this commit, although I suspect there would be a more elegant way to do it: bgrainger@7e572ce.

This may relate to #77.

New F# class library project.
Replace the source file content with

namespace Example

///<summary>
/// Various extension methods
///</summary>
module Extension =
  ///<summary>
  /// F# style extension on Object with no arguments
  ///</summary>
  type System.Object with
    ///<summary>
    /// Checks for being non-null
    ///</summary>
    /// <param name="P_0">The target</param>
    /// <returns>True if not null.</returns>
    member self.IsNotNull
      with get() =
        self |> isNull |> not

  ///<summary>
  /// F# style extension on Int32 with one argument
  ///</summary>
  type System.Int32 with
    ///<summary>
    /// Conditionally increments
    ///</summary>
    /// <param name="self">The target</param>
    /// <param name="b">Increment if true</param>
    /// <returns>The result.</returns>
    member self.Increment (b : bool) =
      self + if b then 1 else 0

  ///<summary>
  /// F# style static extensions on Option
  ///</summary>
  type Microsoft.FSharp.Core.Option<'T> with
    ///<summary>
    /// Turns a null into a None
    ///</summary>
    /// <param name="x">The object to wrap</param>
    /// <returns>Some value, or None for null.</returns>
    static member nullable (x : 'T) : option<'T> =
      if x.IsNotNull then Some x else None

    ///<summary>
    /// Extract value with default
    ///</summary>
    /// <param name="fallback">The default value</param>
    /// <param name="x">The object to unwrap</param>
    /// <returns>The value of the option, or a fallback if None</returns>
    static member getOrElse (fallback : 'T) (x : option<'T>) = defaultArg x fallback

add doc comment output to the project file

  <PropertyGroup>
    <DocumentationFile>$(OutputPath)\$(TargetFramework)\$(AssemblyName).xml</DocumentationFile>
  </PropertyGroup>

dotnet publish
dotnet xmldocmd

All the methods are present in the output, but only the comment on the class Example.Extension is present.

Hyperlink in "Remarks" isn't hyperlinked: https://faithlife.github.io/FaithlifeTracing/Faithlife.Tracing/TraceTagNames.html#remarks

https://github.com/Faithlife/FaithlifeTracing/blob/7a75ea237c6f3394943fa781c5be68d2a0ff4be7/src/Faithlife.Tracing/TraceTagNames.cs#L6

Attempting to do so gives

No compatible framework version

The framework 'Microsoft.NETCore.App', version '3.1.0' was not found.

  - The following frameworks were found:

      5.0.0 at [/usr/share/dotnet/shared/Microsoft.NETCore.App]

You can resolve the problem by installing the specified framework and/or SDK.

A build-time work-around is to add a file runtimeconfig.template.json to the executable project with content

{
  "rollForwardOnNoCandidateFx": 2
}

which roughly says "this application is expected to be forward compatible"

It's all to easy to start processing an assembly and ending up with a ResolutionLoadFailure.

Cases so far encountered that can cause type resolution failures

1. dependency of the .net framework assembly of interest on a .net .exe assembly even if co-located
2. dependency of the .net framework assembly of interest on a system assembly that doesn't get copied to the build output location e.g references to "Microsoft.Build.Framework"and "Microsoft.Build.Utilities.v4.0"
3. when the .net core/standard assembly has been built, but not published, so dependencies are not co-located, but remain in the .nuget cache or other standard locations.

These can be worked around by copying the appropriate files (cases 1 and 2), or using a .net framework target instead for case 3. Cases 1 and 3, however, are susceptible to the use of a ResolveEventHandler.

Feeding xmldocmd an F# project results in source links like

* [WhatIfExtension.cs](https://github.com/SteveGilham/altcover/tree/master/AltCover/WhatIfExtension.cs)

This one is, fortuitously correct in guessing the file name w/o extension, but it seems that the algorithm used to generate the path is simply to take [TypeName].cs, making an assumption of language as well as coding style; when the information required to do it correctly should be present in the associated .pdb files.

I've not yet started reading the code (to see what happens with partial classes), nor trying this with other languages like VB or C++/CLI.

Given that text

/// <summary>
/// Always <see langword="null"/> for all values.
/// </summary>

I receive this generated .md:

Always  for all values.

A vertical bar in a <c> element doesn't render right.

The method signature should show CallerMemberName, CallerLineNumber, and CallerFilePath when used.

https://faithlife.github.io/FaithlifeBuild/Faithlife.Build/BuildRunner/Execute.html

As a team member I'd like to share all the reference API with other developers to help them during maintenance activities. For this reason I'd like to chose, with an option, if generate or not only public members.

The assembly summary contains a count of types and namespaces. This could create merge conflicts for branches that change the number of types. Consider removing it.

E.g.: https://github.com/Faithlife/FaithlifeUtility/pull/8/files#diff-b27f51ccd58cc0b550053fdb6e747a7cR3

Currently, the generated output is along the lines of

• RootElement.md
• RootEelement
  • ChildElement1.md
  • ChildElement2.md

But is there any way we could have it output

• RootElement
  • README.md < Would be handy to have the name of this configurable ie README or Index
  • ChildElement1.md
  • ChildElement2.md

A single configuration item could support an array of namespaces.

We currently just support "same repository" but a Url property could point to an entirely different repository.

Getting the following error

Could not load file or assembly 'Microsoft.AspNetCore.Mvc.Core, Version=7.0.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60'. The system cannot find the file specified.

   at System.Reflection.RuntimeModule.GetTypes(RuntimeModule module)
   at XmlDocMarkdown.Core.MarkdownGenerator.DoGenerateOutput(Assembly assembly, XmlDocAssembly xmlDocAssembly)+MoveNext() in /_/src/XmlDocMarkdown.Core/MarkdownGenerator.cs:line 55
   at System.Collections.Generic.List`1..ctor(IEnumerable`1 collection)
   at System.Linq.Enumerable.ToList[TSource](IEnumerable`1 source)
   at XmlDocMarkdown.Core.MarkdownGenerator.GenerateOutput(Assembly assembly, XmlDocAssembly xmlDocAssembly) in /_/src/XmlDocMarkdown.Core/MarkdownGenerator.cs:line 38
   at XmlDocMarkdown.Core.XmlDocMarkdownGenerator.Generate(XmlDocInput input, String outputPath, XmlDocMarkdownSettings settings) in /_/src/XmlDocMarkdown.Core/XmlDocMarkdownGenerator.cs:line 92
   at XmlDocMarkdown.Core.XmlDocMarkdownApp.Run(IReadOnlyList`1 args) in /_/src/XmlDocMarkdown.Core/XmlDocMarkdownApp.cs:line 70
System.IO.FileNotFoundException: Could not load file or assembly 'Microsoft.AspNetCore.Mvc.Core, Version=7.0.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60'. The system cannot find the file specified.

File name: 'Microsoft.AspNetCore.Mvc.Core, Version=7.0.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60'

Not sure if the multiple frameworks targets are messing up the tool or if it is the Framework reference...

csproj fragment

<Project Sdk="Microsoft.NET.Sdk">

    <PropertyGroup>
        <TargetFrameworks>net6.0;net7.0</TargetFrameworks>
    </PropertyGroup>

    <ItemGroup>
        <FrameworkReference Include="Microsoft.AspNetCore.App" />
    </ItemGroup>

</Project>

We basically ignore links to types not in the assembly being documented. We should design and implement a strategy for those links. I'm already working on some ideas.

Create a new F# Library project with the following source code

namespace ExtensionMethods

open System.Collections
open System.Runtime.CompilerServices

// F# extension style
// implicit `this` parameter has a null name
module Augment =
  type System.Object with
    member self.IsNotNull
      with get() =
        self |> isNull |> not

open Augment

// C# extension style
// no `this` parameter syntactic sugar available
// so explicitly decorate with `ExtensionAttribute`
[<Extension>]
module Utility =
  [<Extension>]
  let SafeLength (x : IEnumerable) =
    if x.IsNotNull
    then  x |> Seq.cast<obj> |> Seq.length
    else -1

and run xmldocmd over the resulting assembly.

The following exception results --

System.NullReferenceException: Object reference not set to an instance of an object.
   at XmlDocMarkdown.Core.MarkdownGenerator.GetFullSignature(MemberInfo memberInfo, ICollection`1 seeAlsoMembers) in C:\projects\xmldocmarkdown\src\XmlDocMarkdown.Core\MarkdownGenerator.cs:line 874
   at XmlDocMarkdown.Core.MarkdownGenerator.<>c__DisplayClass41_0.<WriteMemberPage>b__0(MarkdownWriter writer) in C:\projects\xmldocmarkdown\src\XmlDocMarkdown.Core\MarkdownGenerator.cs:line 250
   at XmlDocMarkdown.Core.MarkdownGenerator.CreateNamedText(String name, Action`1 writeTo) in C:\projects\xmldocmarkdown\src\XmlDocMarkdown.Core\MarkdownGenerator.cs:line 152
   at XmlDocMarkdown.Core.MarkdownGenerator.WriteMemberPage(String path, IReadOnlyList`1 memberGroup, MarkdownContext context) in C:\projects\xmldocmarkdown\src\XmlDocMarkdown.Core\MarkdownGenerator.cs:line 213
   at XmlDocMarkdown.Core.MarkdownGenerator.DoGenerateOutput(Assembly assembly, XmlDocAssembly xmlDocAssembly)+MoveNext()
   at System.Collections.Generic.List`1..ctor(IEnumerable`1 collection)
   at System.Linq.Enumerable.ToList[TSource](IEnumerable`1 source)
   at XmlDocMarkdown.Core.XmlDocMarkdownGenerator.Generate(String inputPath, String outputPath, XmlDocMarkdownSettings settings) in C:\projects\xmldocmarkdown\src\XmlDocMarkdown.Core\XmlDocMarkdownGenerator.cs:line 58
   at XmlDocMarkdown.XmlDocMarkdownApp.Run(IReadOnlyList`1 args) in C:\projects\xmldocmarkdown\src\xmldocmd\XmlDocMarkdownApp.cs:line 55

because the implicit this parameter has a null parameter name.

If we want to support linking to other kinds of external documentation, we could add a Format property. For example, msdocs could conform to the docs.microsoft.com pattern, e.g. https://docs.microsoft.com/en-us/dotnet/api/system.datetime.

We could also support hidden to disable any linking that might otherwise be used.

Internal types are incorrectly displayed and counted as public types in the list of types.

We performed an automated audit of your Cake addin and found that it does not follow all the best practices.

We encourage you to make the following modifications:

• You are currently referencing Cake.Core 0.27.1. Please upgrade to 0.28.0
• The Cake.Core reference should be private. Specifically, your addin's .csproj should have a line similar to this: <PackageReference Include="Cake.Core" Version="0.28.0" PrivateAssets="All" />
• Your addin should target netstandard2.0. Please note that there is no need to multi-target, netstandard2.0 is sufficient.
• The nuget package for your addin should use the cake-contrib icon. Specifically, your addin's .csproj should have a line like this: <PackageIconUrl>https://cdn.rawgit.com/cake-contrib/graphics/a5cf0f881c390650144b2243ae551d5b9f836196/png/cake-contrib-medium.png</PackageIconUrl>.

Apologies if this is already being worked on, or if there are existing open issues, this issue was created based on what is currently published for this package on NuGet.org and in the project on github.

Thanks again for creating this Cake Addin, we really appreciate the effort that you have put in to creating it.

We, the Cake Team, recently announced a new Cake Contrib Icon, details of which can be found here:

http://cakebuild.net/blog/2017/06/new-cake-contrib-icon

Would you consider changing the nuspec file for your NuGet Package to use this new Cake Contrib Icon? If so, the recommended URL to use is:

https://cdn.rawgit.com/cake-contrib/graphics/a5cf0f881c390650144b2243ae551d5b9f836196/png/cake-contrib-medium.png

Details of the above URL can be found in the repository here:

https://github.com/cake-contrib/graphics

Please let me know if you have any questions.

Can you add a file version either to the assembly on disk, or to the help output, so that I can automate upgrading the tool to a specific version? Notice there is no file version on this command line:

d:\git\foundry99\Coyote>filever d:\git\foundry99\Coyote\packages\xmldocmd.exe
--a-- W32x64   -   -               -   -    137,728 02-19-2020 xmldocmd.exe

and here:

If I generate documentation for an assembly (I use Global Tool) that refers to an Newtonsoft.Json version other than 11.0.1 I get following error:

System.IO.FileLoadException: Could not load file or assembly 'Newtonsoft.Json, Version=12.0.0.0, Culture=neutral, PublicKeyToken=30ad4fe6b2a6aeed'. Could not find or load a specific file. (Exception from HRESULT: 0x80131621)
File name: 'Newtonsoft.Json, Version=12.0.0.0, Culture=neutral, PublicKeyToken=30ad4fe6b2a6aeed' ---> System.IO.FileLoadException: Could not load file or assembly 'Newtonsoft.Json, Version=12.0.0.0, Culture=neutral, PublicKeyToken=30ad4fe6b2a6aeed'.
   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.LoadFrom(String assemblyFile)
   at System.Reflection.Assembly.LoadFromResolveHandler(Object sender, ResolveEventArgs args)
   at System.AppDomain.InvokeResolveEvent(ResolveEventHandler eventHandler, RuntimeAssembly assembly, String name)

This happens because version 11 is already loaded into the domain.

Running

dotnet xmldocmd /?

includes

 --skip-compiler-generated
      Skips documentation for types that are marked with System.Runtime.CompilerServices.CompilerGenerated.

amongst the options in the help text, but attempting to use it results in

Unexpected option '--skip-compiler-generated'.

As part of XmlDocMarkdown.Core, presumably.

There's one directory per namespace, and we should clean them all. Since the codegen comment we look for includes the assembly file name, it should be safe to clean all directories, even if multiple projects generate docs to the same parent directory.

Running the tool via dotnet xmldocmd against a project built using ASP Net Core 3.1 fails with the following exception.

System.Reflection.ReflectionTypeLoadException: Unable to load one or more of the requested types.
Could not load file or assembly 'Microsoft.AspNetCore.Mvc.Core, Version=3.1.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60'. The system cannot find the file specified.
   at System.Reflection.RuntimeModule.GetTypes(RuntimeModule module)
   at System.Reflection.RuntimeAssembly.get_DefinedTypes()
   at XmlDocMarkdown.Core.MarkdownGenerator.DoGenerateOutput(Assembly assembly, XmlDocAssembly xmlDocAssembly)+MoveNext() in C:\projects\xmldocmarkdown\src\XmlDocMarkdown.Core\MarkdownGenerator.cs:line 41
   at System.Collections.Generic.List`1..ctor(IEnumerable`1 collection)
   at System.Linq.Enumerable.ToList[TSource](IEnumerable`1 source)
   at XmlDocMarkdown.Core.XmlDocMarkdownGenerator.Generate(String inputPath, String outputPath, XmlDocMarkdownSettings settings) in C:\projects\xmldocmarkdown\src\XmlDocMarkdown.Core\XmlDocMarkdownGenerator.cs:line 58
   at XmlDocMarkdown.XmlDocMarkdownApp.Run(IReadOnlyList`1 args) in C:\projects\xmldocmarkdown\src\xmldocmd\XmlDocMarkdownApp.cs:line 55
System.IO.FileNotFoundException: Could not load file or assembly 'Microsoft.AspNetCore.Mvc.Core, Version=3.1.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60'. The system cannot find the file specified.
File name: 'Microsoft.AspNetCore.Mvc.Core, Version=3.1.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60'

I'm guessing this is due to 3.0+ being pulled in as a framework now rather than NuGet packages so the DLLs aren't in the output folder and the assembly manifest just references the metadata reference assemblies from another folder.

I had to add System.Runtime.Serialization.Primitives.dll to the tools directory in the package locally in order to generate documentation. Getting a FileNotFound exception without it.

I've downloaded the latest release file and compiled locally to try out the --namespace-pages flag but from my findings it's not quite working correctly.

Running this on a DLL I seem to get a mixture of some namespace pages, but then still an assembly page that contains some other namspaces that haven't been broken out.

I'd expect the --namspace-pages flag to extract all namspaces to individual pages, not just some.

I have some classes that I need to document because they are public, but they are intended for compiler use only, like custom implementations of AsyncControlledTaskMethodBuilder. So I need to document them for intellisense, but I'd like to strip them out of the docs.

I propose some sort of tag in the xml doc comment that signals XmlDocComment to ignore that class like:

/// <![CDATA[nodoc]]>

Alternative would be to use the following, but the downside to this is it has other implications:

[System.ComponentModel.EditorBrowsable(System.ComponentModel.EditorBrowsableState.Never)]

Or we have a completely separate --blacklist file that is input to the generator, but I would prefer something in the code since that is more maintainable.

This may not be the right title for this but essentially, I'm looking at the code and there are a lot of things implemented specific for Jekyll which is rather inflexible for people who are using something different that expects different formats.

It would be good if these framework specific needs could be encapsulated in some kind of plugin architecture such that these can be chopped and changed depending on peoples needs and this tool becomes useful for more than just Jekyll users.

https://faithlife.github.io/FaithlifeBuild/Faithlife.Build/MSBuildRunner/RunMSBuild.html

If i try to run with a Uwp dll, results the follow error message in the command prompt:

System.BadImageFormatException

Is there a way to work with Uwp dll?

We should document the .NET Core Global Tool.

Lots of pattern matching opportunities, for example.

See https://github.com/ejball/FaithlifeUtility/blame/c61273cc735a7b20b73fb9a3ec629ab8f706a9ac/docs/Faithlife.Utility/RebasedStream.md#L13

generated from https://github.com/ejball/FaithlifeUtility/blob/c61273cc735a7b20b73fb9a3ec629ab8f706a9ac/src/Faithlife.Utility/RebasedStream.cs#L11-L12

When finding external documentation configuration, we should match descendant namespaces. If there are multiple matches, we should use the longest match.

I implemented a custom MS Build Task (Microsoft.Build.Utilities.Task) to automatically generate documents for all .xml files in a build output. It works fine the first run, but the default MSBuild reuse behavior is causing locks to any assembly loaded by the Generate method because it uses the Assembly.Load method. To prevent this, you have to read the assembly as a byte array and pass it to a new AppDomain.

AppDomain ad = AppDomain.CreateDomain("MyNewDomain");
byte[] assemblyBytes = File.ReadAllBytes("<path to assembly>");
var assembly = ad.Load(assemblyBytes); 

EDIT:
Well, crud. AppDomains are not supported in .NET Standard (and won't be). So now to figure out an alternative...

This issue may be related to some of the existing external document issues, but none of them seem to capture the heart of my concern.

Example Situation

I have a solution with several class libraries and several unit test projects. I'd like to have documentation for all of the libraries, but none of the unit test projects. There are also dependencies between projects. For example, one library may define an interface, and another library may implement that interface using a specific technology.

Running xmldocmd on specific dlls or looping over them works on the surface but does not generate links between the individual documents generated for each dll.

Trial and error showed me that I could use --external multiple times on a command line to generate the correct links.

My POC batch file went from something like this:

xmldocmd library1.dll output
xmldocmd library2.dll output

to

FOR %%i IN (library*.dll) DO xmldocmd %%i "output" --external ns1 --external ns2 --external ns3

This made all of my documents and linked them together but also got confused about generics. This may be a separate issue, but when a namespace specified with --external is found in the assembly being processed, it would try to generate links to a file for the generic type parameter.

Desired Behavior

I realize some of this is a stretch, but here are what I think would be best in order of best to worst.

1. Ideally, I could tell it to generate documents for a solution, and it would create documents for all assemblies that create the XML documentation files.
2. If I could specify a solution file, the next thing would be to be able to specify a list of assemblies to create XML documents for one line.
3. If it was to keep to one assembly per command, like it is now, then it could look for referenced assemblies, in the same folder, and generate links for those assemblies. Assuming that they have XML files.
   This option seems like it can get complicated fast since there will be issues if some of the assemblies don't get documents created or get them created in the wrong locations. That is why the previous options are preferred since there is enough context to know which documents are being created and where.
4. Another step closer to the current implementation would be to specify --external assemblies instead of namespaces and generate links for all of the namespaces in the assembly.
   The assumption here is that, if an assembly is specified, then the caller is ensuring that the documents were created for that assembly in the same location.

No matter which option is selected, it would create links between the documents for each assembly as if they were in the same assembly. (Or if you prefer, as if they had the appropriate --external namespaces defined.)

My Temporary Work Around

As a temporary measure, I have added a command-line program that references the XmlDocMarkdown.Core (2.02) NuGet package.
It does the following.

1. "Selects" all of the assemblies, created by my solution, that created XML documents.
2. Reflects over each selected assembly and creates a map of assemblies and namespaces.
3. Runs XmlDocMarkdownGenerator.Generate for each assembly, with the XmlDocMarkdownSettings.ExternalDocs set to a distinct list of the namespaces for all of the assemblies except the current one.
   • This is to avoid the issue with the generics mentioned above.

Side Note

--external option is not part of the help displayed when executing the command, I found it on the site, and it wasn't at all clear how to specify more than one namespace.

--external : Generates links to external documentation for the specified namespace.

Some class has 3 constructors

		''' <summary>
		''' Constructor from global properties.
		''' </summary>
		''' <param name="accessMode">Mode of access to stored items.</param>
		''' <param name="guidStrictionMode">Mode processing GUIDs for newly added items.</param>
		Protected Sub New(accessMode As AccessMode, guidStrictionMode As GuidStrictionMode)
			' Do somthing
		End Sub

		''' <summary>
		''' Cloning constructor.
		''' </summary>
		''' <param name="prototype">Instance to be cloned.</param>
		Protected Sub New(prototype As OmniCartesianBase(Of TKey, TVal, TBounds))
			' Do somthing
		End Sub

		''' <summary>
		''' Reading Constructor
		''' </summary>
		''' <param name="r">Reader to read from</param>
		''' <param name="accessMode">Mode of access to stored items.</param>
		Protected Sub New(r As Util.IO.OmniReader, accessMode As AccessMode)
			' Do somthing
		End Sub

The expected behavior is to get documentation for each, but I get another:

OmniCartesianBase<TKey,TVal,TBounds> constructor (1 of 3)

protected OmniCartesianBase(OmniCartesianBase prototype)

See Also

• class OmniCartesianBase<TKey,TVal,TBounds>
• namespace dpOmni.Collection

OmniCartesianBase<TKey,TVal,TBounds> constructor (2 of 3)

Constructor from global properties.

protected OmniCartesianBase(AccessMode accessMode, GuidStrictionMode guidStrictionMode)

See Also

• enum AccessMode
• enum GuidStrictionMode
• class OmniCartesianBase<TKey,TVal,TBounds>
• namespace dpOmni.Collection

OmniCartesianBase<TKey,TVal,TBounds> constructor (3 of 3)

protected OmniCartesianBase(OmniReader r, AccessMode accessMode)

See Also

• class OmniReader
• enum AccessMode
• class OmniCartesianBase<TKey,TVal,TBounds>
• namespace dpOmni.Collection

As You can see well documented is only the first constructor (Protected Sub New(accessMode As AccessMode, guidStrictionMode As GuidStrictionMode))

Class is fully-functional and inside Visual Studio all documentation shows correctly as in example below:

Only documented when --visibility private, they are currently documented with non-static constructors, but they probably deserve their own page.

I'm calling XmlDocMarkdownGenerate in Cake with a Xamarin.iOS library dll.
It throws the following exception:

System.TypeLoadException: Could not load method 22 due to Could not load file or assembly 'Xamarin.iOS, Version=0.0.0.0, Culture=neutral, PublicKeyToken=84e04ff9cfb79065' or one of its dependencies.

1 - How can I add dependent assemblies?

2 - There is any way of generating the documentation from source code instead of .dll?

Since .net core/standard do not copy NuGet dependencies to the output folder xml doc comments that reference items from external dependencies pulled in by packages are not found by the tool when generating the documentation as appears to only be resolving the assemblies from the output folder.

I can currently work around this with a build step that copies the missing DLLs from the %USERPROFILE%.nuget\packages folder to the output folder but ideally the tool should check there to resolve assembly dependencies.

Would be nice if I could provide a front matter template for Github pages, something like this:

---
layout: reference
title: $title
section: learn
permalink: /learn/ref/$ref
---

Also it would be nice if the folder hierarchy produced was compatible with Jekyll. If you have class A with member M1 and M2 you get:

.../A.md
.../A/M1.md
.../A/M2.md

But if I want to turn these links into Jekyll "permalinks" it won't work because you can't have the top level "/A" and another page with link "/A/M1". This is a limitation of github pages I guess. So the new structure would need to be this instead:

.../A/Type.md
.../A/A.md        (constructor)
.../A/M1.md          
.../A/M2.md

And the associated relative links then between A_Type.md and M1 and M2 would need to be rewritten... so the permalink for the class is ".../A/Type" and it points to members using relative links M1 and M2. The members point to the class using relative link Type. Constructor uses permalink ".../A/A". So relative links to the constructor are just A. Similar problem happens with the Assembly level markdown, which would need to be moved inside the similarly named Namespace if there is one, perhaps named "Assembly.md" or something.

Code authors can use <inheritdoc/> to "inherit XML comments from base classes, interfaces, and similar methods" (source).

The most common use case is when overriding a base class method, but the documentation implies that you can "add your XML comments to your synchronous methods and let InheritDoc copy the comments to your asynchronous versions of the same methods."

It would be nice if XmlDocMarkdown supported:

1. Inheriting documentation for overridden methods.
2. Copying sync method documentation to async methods.

XmlDocMarkdown.csproj contains the following section which, as far as I can tell, serves no purpose at all:

<ItemDefinitionGroup>
    <PackageReference>
    <PrivateAssets>all</PrivateAssets>
  </PackageReference>
  <ProjectReference>
    <PrivateAssets>all</PrivateAssets>
  </ProjectReference>
</ItemDefinitionGroup>

Visual Studio seems to be be able to ignore this useless section, however it's causing the project parser in Cake.Incubator to throw ArgumentNullException when we attempt to parse the content of this project file.

The cake-contrib organization has an automated process that disocvers and audits all addins to check if they follow best practices, reference latest version of cake DLLs, etc. Unfortunately, this issue is preventing the automated process to audit the Cake.XmlDocMarkdown addin.

I suggest removing this ItemDefinitionGroup section which, hopefully, will allow the automated process to audit your addin.