DocFx doesn't take <include> tag into account.

[cr-chris]

DocFX Version Used: 2.28.3

Template used: default

Steps to Reproduce:

1. Create a "documentation.xml" file at the root of project.

<?xml version="1.0" encoding="utf-8" ?>
<Documentation>
  <MyClass>
    <MyMethod>
      <remarks>
        One remark
      </remarks>
    </MyMethod>
  </MyClass>
</Documentation>

2. Add the tag on the top of a method.

/// <summary>
/// This method should do something...
/// </summary>
/// <include file='../Documentation.xml' path='Documentation/MyClass/MyMethod/*'/>
public void OneMethod()
{

}

3. Compile documentation

Expected Behavior:

The Remarks topic should be displayed on the documentation page.

Actual Behavior:

The Remarks topic doesn't appear.

Is the tag supported by DocFx ?

[vicancy]

This is not supported for now.

[smaillet]

Will this ever be supported? It's a blocker for a project I'm working on. I'm unclear on how this isn't supported since the C# compiler is what processes the include to produce the final doc comments .xml for an assembly at compile time - so why does docfx get in the middle of things to actively block this?

[KalleOlaviNiemitalo]

DocFX is able to extract the metadata and documentation of your APIs in two ways:

• From source files via the Roslyn API. Maybe it does not support the include element in this case.
• From EXE/DLL and XML files generated by the compiler. I believe the include element will work in this case, because the compiler has already processed it.

[Konard]

Please add support for it. @KalleOlaviNiemitalo how to set up the path to generated XML documentation for DocFX to use it?

[KalleOlaviNiemitalo]

@Konard, add this kind of thing to docfx.json:

{
  "metadata": [
    {
      "src": [
        {
          "files": [
            "src/*.dll"
          ]
        }
      ],
      "dest": "api"
    }
  ]
}

It finds src/*.dll and then automatically uses the corresponding XML files if they are in the same directory as the DLL files. https://github.com/dotnet/docfx/blob/4f1574f0a41508486127fcdf6395e0e5fafb0dd2/src/Microsoft.DocAsCode.Metadata.ManagedReference/ExtractMetadataWorker.cs#L340-L343

[Transeric]

Please add support for this tag. Otherwise, the usability of this great tool is severely diminished. Some of us are creating API documentation where we would like to include examples (via the C# example/code tags). Without the include tag, this is really not possible. The code simply becomes way too littered...to the point of unreadability.

The tag no longer seems limited to Sandcastle. Its now included in Microsoft's official C# documentation:

https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/include

This page even indicates that its already supported by DocFx: "consumed by documentation tools such as DocFX and Sandcastle to produce the final documentation". Come on guys...how hard can this be...don't make a liar out of the MS docs :)

[KalleOlaviNiemitalo]

Some of us are creating API documentation where we would like to include examples (via the C# example/code tags).

As a workaround, you could place the code snippets in separate source (not XML) files and use Code Snippet syntax in DocFX Flavored Markdown. That would even let your continuous integration system test the code snippets. The Go to Definition feature of Visual Studio would not show the code snippets, but IIRC <code> would not look good there either.

This page even indicates that its already supported by DocFx: "consumed by documentation tools such as DocFX and Sandcastle to produce the final documentation".

<include> works if you make DocFX consume the compiler-generated XML like the documentation says.

[Transeric]

As a workaround, you could place the code snippets in separate source (not XML) files and use Code Snippet syntax in DocFX Flavored Markdown.

@KalleOlaviNiemitalo, thank you for the suggestion. I'll definitely keep it in mind, and most likely use it, for future projects. Regrettably, my rather large code base already uses include tags extensively. Finding the time or budget to go back and change them all over (to make DocFX happy) is probably a non-starter :)

works if you make DocFX consume the compiler-generated XML like the documentation says.

Perhaps this is an option. Could you please elaborate? I'm not certain I understand what you're proposing. For background, I am currently generating documentation via VS builds using the NuGet package variant of DocFX.

[KalleOlaviNiemitalo]

@Transeric, do you mean the docfx.console package? It seems to install a docfx.json file that refers to ".csproj". As I wrote earlier in this issue, if you change docfx.json to refer to .dll or *.exe files instead (don't let DocFX see the project files and source files at all) and tell the C# compiler to generate an XML documentation file, then \<include> should work.

[Transeric]

@KalleOlaviNiemitalo, yes the docfx.console package. Thanks, I'll give the *.dll trick a try. Though, I still maintain the include tag should "just work"...whatever input you choose. It can't be that hard to support.

[Transeric]

@KalleOlaviNiemitalo, I wanted to thank you again for your suggestions regarding code snippets. They were extremely helpful. The feature is absolutely awesome!

I'm definitely going to use it. I'm going to place the markdown for code-snippets in my C# XML comments, within the <example> tags. The only real challenge was figuring out the "correct" relative path for the source file, but I've got that sorted now. It would be nice if the DocFX documentation provided some examples of how to use [!code-<language>] markup within source code and discussed the root for those relative paths.

Now, I'm down to dreading the amount of work its going to take me to re-do all of my comments, but should be worth it.