C# XML Doc element `include` is not part of generated documentation

[deap82]

Hi, I'm trying out Wyam for documenting a C# code base and in the code there is a case where xml doc comments are shared across a few (similiar) classes using the include xml doc element, documented here; https://docs.microsoft.com/en-us/dotnet/csharp/codedoc#include

However, when using Wyam with the Docs recipe the contents of these referenced xml files are not included in the Wyam generated docs site. I tried to point to my AssemblyFiles instead of the SourceFiiles, but then I end up with no API item in the main menu at all. I'm not sure if I'm doing it right;

Settings[DocsKeys.AssemblyFiles] = "src/**/obj/Debug/**/*.dll";
Settings[DocsKeys.SourceFiles] = null;

For the assembly that has these doc comments with include elemnets, msbuild also produces an .xml file on the form AssemblyName.xml in the same folder as the .csproj file. This xml file does include the docs referenced from the include elements, ie repeated for each time it is referenced.

I'm thinking maybe that file is of interest and in the Wyam docs for the "Docs" recipe it says that features of the recipe includes:

API documentation from assemblies (with or without XML documentation file from MSBuild). (https://wyam.io/recipes/docs/overview)

Could someone clarify how to make use of that generated XML documentation as input for Wyam generation?

[daveaglick]

Thanks for the bug report. This used to work (in fact, the Wyam site includes Razor documentation through an external XML file). At some point though it looks like there was a regression. My guess is that we lost the capability with a Roslyn upgrade (Wyam uses Roslyn to provide the XML comments via the compiler). I’ll dig deeper and see if I can’t restore the ability in the next release.

[deap82]

@daveaglick Any update on this?

[daveaglick]

@deap82 No, not yet - unfortunately it might be a little while. I'm working furiously on some larger-scale changes to try and get v3 out the door (follow along in the vnext branch). In order to focus on that I had to draw a line and put off other issues (otherwise it might never get done). There's a lot of good bugs and small features like this one at the top of the issue list that I'll tackle as soon as v3 is out the door.

[skini82]

@daveaglick Hi and thanks for your effort! There's a known version where this still works? I really need the XML inclusion.

[dave-sampson13]

@daveaglick Similar query, any ETA on a fix for this? We have some third-party dependencies that we want to document as part of our API documentation, but don't have the source code so are dependent on the ability to extract documentation from the assemblies &| XML comments files. Thanks!

[daveaglick]

@skini82 @dave-sampson13 Sorry folks, I don't have an ETA. Work is progressing at a fast clip on v3 (which is now called Statiq and all new development is happening there. I'm going as quick as I can, but it's probably another couple months until that reaches release and this issue is resolved.

Note that docs generated from assemblies will still pick up on compiler-generated XML documentation comments. This issue tracks the special <include> XML comment element that references an explicit XML comment file. For example, the Cake documentation downloads NuGet packages for all known addins here and then adds the resulting assemblies to the Wyam docs generation here. You can see the result, which picks up on any compiler-generated XML documentation files, at any API docs page for an addin like https://cakebuild.net/api/Cake.Dart/.