DotNet API Docs

DocFX turns the XML documentation comments of a .NET code base into a browsable API reference. You write the comments in the source as usual (the syntax itself is covered in C# coding conventions and documentation and, for Visual Basic, in Visual Basic XML documentation, analyzers and code style), and DocFX produces one page for each namespace, type and member, with signatures, parameter tables, links between types and links to the Microsoft Learn pages of the framework types you use.

The work happens in two stages that can run on their own:

The official documentation notes that the Docset.Build method does not run the metadata stage; code that drives DocFX from a program calls DotnetApiCatalog.GenerateManagedReferenceYamlFiles first (see the custom filter section below).

The figure follows the Pocket Units converter through both stages. The comment text is Markdown. The metadata stage converts the XML tags such as paramref to HTML but leaves the Markdown in the text untouched, and the build stage renders that Markdown into the page. The member marked with the exclude tag never reaches the YAML.

The library is the Pocket Units length converter. Its layout is:

The project file targets net8.0 and enables GenerateDocumentationFile. The converter carries the comments that the rest of the page works with: Markdown inside remarks and returns, an example, a seealso, an obsolete member and a member marked with <exclude />:

Source: DocFX docs: .NET API Docs

The library also has a PocketUnits.Formatting namespace with a UnitFormatter class, a PocketUnits.Internal namespace with a public Cache class that is an implementation detail, and the LengthUnit enum with the members Metre, Kilometre, Foot and Mile in that declaration order.

The metadata.src array selects what DocFX reads. Each entry is a file mapping: files lists glob patterns, src is the folder they are resolved against (a path relative to docfx.json, which may point outside the folder with ..) and exclude removes matches. Glob patterns themselves cannot walk out of the folder that holds docfx.json, which is why a documentation project that lives next to the library uses src for the hop. DocFX supports four kinds of input, which the official page distinguishes by file extension.

Source: DocFX docs: .NET API Docs

For project and solution input DocFX runs dotnet restore first. Since 2.80.1 it stops the metadata stage when the restore fails. Set noRestore to true to skip the step when the projects are already restored, for example because a previous CI step did it. This is what happens if you set it and the project has never been restored:

DocFX exited with code 255 and wrote no files. After dotnet restore in the project folder the same configuration, with "noRestore": true, succeeded. A missing restore therefore does not say "run restore"; the compiler errors about System are the signature of the problem.

properties passes MSBuild properties, like the /property:name=value option of dotnet build. The most common use is TargetFramework. A project that targets several frameworks is built once for each of them, and the official page suggests naming one to make the stage faster:

Source: DocFX docs: .NET API Docs

The page does not say that a multi-targeted project fails without it. A copy of Pocket Units with <TargetFrameworks>net8.0;net10.0</TargetFrameworks> produced the API files both with and without the property. Two rules of the reference are worth keeping in mind. For source-file input only DefineConstants and AllowUnsafeBlocks are honoured and any other property is ignored without a message. And references is used for assemblies and source files, not for solution or project input, which take their references from the project.

DocFX publishes an SDK compatibility report that is refreshed by a nightly workflow of its repository. It records which .NET SDK and project target framework combinations the tool was able to read, and its authors state that the results are automated observations and not a support guarantee; a combination that is not in the matrix has no claim either way. The configured matrix, as described in the maintenance guide of the report, has five rows of SDK and project target:

Source: DocFX docs: SDK compatibility

Each row runs two scenarios: a plain C# class (its public type and method must appear in the metadata) and a Razor component with @inherits and a code-behind override. Each row is run against the released DocFX tool (target net10.0) and against the nightly tools built for net8.0, net9.0, net10.0 and net11.0, on Linux only. The columns of the report show the DocFX version and the tool target framework, not the target of your project. The report is a good first stop when a newer SDK fails to read a project, because source generators shipped with an SDK can need a newer Roslyn compiler than the one bundled with an older tool target.

DocFX 2.81.0 adds a .NET 11 release-candidate target and keeps the 8, 9 and 10 targets. In the scratch environment of this page, the 2.81.0 tool read a net8.0 project and a net10.0 project with the SDK 10.0.403 without problems.

DocFX treats the text inside the XML tags as Markdown. The Pocket Units comments use **stateless** and an inline link in remarks, and backticks in returns. After the metadata stage the Markdown is still in the YAML, converted only where an XML tag was involved (the see and paramref tags become xref and code elements):

Source: DocFX docs: .NET API Docs

The build stage renders them, so the page contains <strong>stateless</strong>, an anchor for the NIST link and <code>3.28</code>. The same comments appear in the IntelliSense window of an editor, which does not render Markdown, so heavy formatting there looks like noise. Setting shouldSkipMarkup to true makes DocFX leave the text alone. The YAML then records shouldSkipMarkup: true, and the build leaves the characters as written: the built page showed **stateless** and the backticks literally.

Source: DocFX docs: .NET API Docs

DocFX supports the recommended XML tags of the C# language reference. The ones used above produce these parts of the rendered page: summary the description under the heading, param the Parameters list, returns the Returns list, exception the Exceptions list, seealso the See Also list, example the Examples section and remarks the Remarks section. The example tag has to be a sibling of remarks. When the example was nested inside remarks, the built page showed it as a raw example element inside the Remarks text instead of an Examples section. codeSourceBasePath is the base folder for <code source="Example.cs"/> references, which pull code for examples from a file instead of the comment.

By default DocFX documents only the types and members that code in another assembly can call. It also applies a built-in set of filter rules, in defaultfilterconfig.yml in the DocFX repository, which hide common patterns such as members marked with EditorBrowsableAttribute. There are several ways to hide more, from the narrowest to the broadest.

Three options of the metadata section decide how the API is organized in the table of contents and in the pages.

Source: DocFX docs: docfx.json reference, metadata

With the defaults the generated toc.yml of Pocket Units lists PocketUnits and PocketUnits.Formatting as two siblings, ends with memberLayout: SamePage, and the enum members come out as Foot, Kilometre, Metre and Mile. With "namespaceLayout": "nested", "memberLayout": "separatePages" and "enumSortOrder": "declaringOrder" the same file becomes:

Source: DocFX docs: docfx.json reference, metadata

The enum members are Metre, Kilometre, Foot and Mile, and the build wrote one page for each member, for example _site/api/PocketUnits.Converter.Convert.html and _site/api/PocketUnits.Formatting.UnitFormatter.Format.html, next to the type pages. Nested layout is only visible when the namespaces share a prefix. The global namespace has no name; set globalNamespaceId if you want one.

The View Source link on each page depends on Git information. disableGitFeatures removes the links. For assemblies, the link comes from Source Link data in the .pdb. Version 2.81.0 added sourceLinkExclude, a list of glob patterns matched against source document paths (for a DLL the path recorded in the PDB, which may come from another machine) to hide the link of selected documents, for example generated files, without removing the APIs. It defaults to an empty list, matching is case-insensitive and any matching pattern excludes the document. The reference shows **/ExampleGenerator/** to hide the links of all files from a source generator. This option was not exercised here because the sample has no Source Link mappings.

Putting the choices together, this is the docfx.json used for the final run. The build section reads the generated YAML, the table of contents and the Markdown articles, and uses both templates:

Source: DocFX docs: .NET API Docs

Running docfx docfx.json ended with:

The generated page for Convert has a Parameters list (value, from and to, with the types linked to LengthUnit or to learn.microsoft.com for double), a Returns list, an Exceptions list and a See Also list, all taken from the comment. The toc.yml in the root (a link to the api/ folder) and the other TOC keys are covered in Table of Contents. How <see cref="LengthUnit"/> becomes a link, and how to link to the framework or to other sites, is in Links and Cross References. The meaning of every other key of the file is in docfx.json.