Documenting APIs in assemblies guarded by define constraints

Define constraints in Unity can be used to control whether code in an assembly is available by whether a particular set of preprocessor symbols are defined. If a package conditionally includes an assembly by using define constraints, the APIs in that assembly are not automatically discovered and included in the generated documentation. To include these APIs in the generated documentation, you must define the required symbols.

To define symbols in a local Unity project that you use to generate documentation, add the symbols to the Scripting Define Symbols list in the Player settings. However, defining symbols in the local Player settings does not define the symbols in the project used by Yamato to generate and publish public documentation.

To define symbols for the Yamato server job that generates and publishes public documentation, you must add the symbols to the projectMetadata.json file (in the package's Documentation~ folder). You might need to create this file if it doesn't already exist. Add the symbols as a semicolon-separated list in the pmdt-additional-preprocessors variable in the metadata file. Refer to Code generation settings for more information. Adding the symbols to the metadata file does not define the symbols for your local Unity project.

Important

You must define symbols used in the define constraints of an assembly in BOTH the projectMetadata.json file and your project's Scripting Define Symbols list in order for the docs that you generate locally to match the docs published by the Yamato CI job. If you fail to add the symbols to the projectMetadata.json file, then the docs for APIs in the guarded assemblies won't be included in the published, public documentation.

The Yamato publishing job adds the symbols from the pmdt-additional-preprocessors variable to a .rsp file in the project before regenerating the .csproj files.