Code Project Generation

DocFX requires "proper" C# project file(s) that references the package source code files and the correct compiled code libraries in order to generate the Script Reference with links to types defined outside of the current package. This allows, for example, DocFX to create a link from a graphics package API using Texture to the core Unity Script Reference. Without a proper project file, DocFX, just puts in the bare type name with no link and no namespace. Readers have no way to know where a given type came from and no easy way to navigate to more docs about that type.

The Package Manager Doc Tools (PMDT) relies on the running Unity Editor to provide the context for defining which version of the Unity libraries to reference in the project. For example, if the running Editor is version 2020.3, then only types available in 2020.3 can be linked. The destination of the links is determined by the xrefmap resolution step.

PMDT supports two methods of specifying .NET API code project(s) for DocFX to analyse and extract API documentation:

  1. A generated monolithic code project file generated by PMDT (Monolithic generation)
  2. A selection of assembly-specific code project files generated by an IDE support package built into Unity (Built-in generation)

Monolithic generation

This is the default method for specifying a .NET API code project for DocFX to analyse. Every .cs file included in the target package is included in a single .csproj file. The only preprocessor constants defined in this project are PACKAGE_DOCS_GENERATION and those supplied in the optional DefineConstants setting. Further information.

This is a legacy method for generating a code project and remains the default method for backwards compatibility. In DocFX 2.70.0 and above (required by PMDT 3.0.0 and above) this generated project gives rise to the following new code generation errors in some cases:

  • error CS0227: Unsafe code may only appear if compiling with /unsafe.
  • error CS0122: '<member in Unity or a dependent package>' is inaccessible due to its protection level: Inheriting from private members in friend assemblies. Packages may allow dependent packages to inherit from their members by using the InternalsVisibleTo attribute. Monolithic project generation does not generate or name target assemblies correctly to allow InternalsVisibleTo friend assembly specification to work.
  • error CS0246: The type or namespace name 'NUnit' could not be found (are you missing a using directive or an assembly reference?)

Enable the Ignore API documentation build errors setting to demote these build errors to warnings.

Built-in generation

This is an experimental method for specifying a .NET API code project for DocFX to analyse. It requires the use of a built-in IDE support package, which require their matching IDE to be installed, and global Editor preferences to be configured.

There are two currently supported IDE support packages tested with this method:

Built-in .csproj generation must be enabled in the External Tools sub menu in Unity's User Preferences:

PMDT attempts to locate a generated .csproj file for each Assembly Definition included in the package and an additional Player.csproj file for each assembly if Generate .csproj files for: ... Player projects is enabled in User Preferences. Each matching .csproj file is copied to a temporary directory and listed in the generated DocFX config file metadata section.

Preprocessor directives in built-in projects

.csproj files generated by the supported IDE support packages contain Unity version-specific and assembly-specific preprocessor directives, for example a file Unity.RenderPipelines.HighDefinition.Editor.csproj generated by Unity 2021.3 for HD Render Pipeline will include among others the following preprocessor symbols:

  • UNITY_2021_3_OR_NEWER
  • UNITY_EDITOR

PMDT adds PACKAGE_DOCS_GENERATION and any additional symbols from DefineConstants in Documentation~/config.json. Further information.

Another project file is also generated by HD Render Pipeline for its runtime assembly Unity.RenderPipelines.HighDefinition.Runtime.csproj. This also includes a UNITY_2021_3_OR_NEWER preprocessor but deliberately does not include UNITY_EDITOR. If Player projects is enabled in User Preferences - External Tools an additional project is created Unity.RenderPipelines.HighDefinition.Runtime.Player.csproj.

It is common in package code to conditionally compile API definitions using the UNITY_EDITOR directive in source files that are common to Editor and Runtime assemblies. Both Editor and Runtime .csproj files are submitted to DocFX for code analysis, one of which includes UNITY_EDITOR. The resulting documentation is more complete by default without editing the package source code to add PACKAGE_DOCS_GENERATION to conditional statements, or to specify UNITY_EDITOR in DefineConstants inside Documentation~/config.json.

These preprocessor constants reflect the context in which Unity built the target package source code and its dependencies.

Which generation method is best?

Neither method is correct. A UPM package is usually shipped as source code and assembly definitions that specify one or more assemblies. These assemblies may include code that generates an API. The API in a UPM package assembly compiled by Unity may be different due to conditional compilation. For example different preprocessor definitions may be supplied by different versions of Unity, by project settings, or by the presence of other packages in a project. DocFX and PMDT cannot accurately predict every valid combination of preprocessor directives that may be applied to a given UPM package. It is not possible to guarantee a fully documented API.

Built-in generation produces fewer compilation errors in DocFX 2.70.0+ because the generated projects more accurately reflect how Unity generated the package assemblies, and any dependent package assemblies, that DocFX is attempting to analyse in the current project. The assembly-specific .csproj files contain a matching list of source files, and specify a target assembly name that allows InternalsVisibleTo attributes in dependency packages to successfully list them as friend assemblies.

Monolithic generation includes almost no preprocessor directives automatically. Built-in generation includes many preprocessor directives automatically. Either case may prevent DocFX from conditionally including an API defined in code by default, and either case may necessitate adding PACKAGE_DOCS_GENERATION to package code to document the effected API.

Built-in generation is recommended for PMDT 3.0.0 and above.