Tools

The PMDT Tools menu in the Unity Editor provides some potentially useful utilities for helping the documentation effort. These include:

  • Doc Compiler: Compiles a chosen package's code with the -doc compiler option turned on. Warnings and errors are logged to the Unity console. If you double-click an entry in the console, the Editor attempts to open the file and show the source line responsible for the warning.
  • List Assembly Define Constraints: Logs all assemblies in the project, including in packages, to the Unity console. This tool is helpful for identifying assemblies containing code that currently cannot be documented -- there is currently no way to specify symbols to satisfy define constraints in the Yamato doc generation jobs.
  • YAML ID Search: Look up class names by YAML ID. Primarily, this tool is used to generate the YAML Class ID Reference markdown file for the core manual.
  • Package Documentation Link Report: Compares the versions used in links from the core manual to package docs against the version in the Editor manifest.

The Tools assembly is guarded by a define constraint. To enable the PMDT Tools menu, add the PMDT_TOOLS symbol to your Scripting Define Symbols in your project's Player settings.

Doc Compiler tool

Use this tool to find undocumented APIs and other problems in the API source code comments. The best thing about it is that you can double-click a warning or error in the Unity console to open the offending file.

Note the following caveats about this tool:

  • It uses the deprecated AssemblyBuilder class.
  • It is not the same compiler used by the docs, so it might interpret things differently.
  • It doesn't know anything about filter.yml or other ways we exclude public APIs from documentation, so it might report unneeded docs as missing.
  • It compiles the code, not just the documentation, and might provide warnings and errors unrelated to documentation comments.
Tip

You can prevent Unity from clearing the console after every change to a code file, by unchecking the console's Clear on Recompile option. (You can find this setting in the drop-down menu attached to the Clear button at the top of the Console window.) Disabling the Auto-refresh option in your Unity Preferences is another option.

YAML ID Search tool

The YAML Class ID Reference markdown file needs to be regenerated periodically to account for changes in the Unity API. This is a manual process.

Note that you can also use the tool to look up single ids or a limited range of ids if you have need for that information.

To generate the full Class ID markdown page:

  1. Open the version of the Unity Editor that needs this file updated.

  2. Run PMDT Tools > YAML ID Search to open the window.

  3. Dock the window somewhere in the Unity Editor (so you can see the whole UI).

  4. Set the report parameters:

    • Report path: anywhere you like
    • Report starting ID: 0
    • Report ending ID: 2147483646

  5. Click the Generate Markdown File button.

  6. Wait.

  7. Wait longer.

  8. Find the file at the path you saved it, double check its contents, and copy it to the md folder of the Unity Editor version you are updating.

Note

2147483646 is the maximum 32 bit integer (minus one), which is the highest YAML ID possible. The window provides a rough time estimate, which is based on my M1 Mac.

Typically, links from the core Unity manual to package documentation should use a version that is no older than that package's entry in the Unity Editor manifest for a given version of Unity (or use @latest when the latest version of a package is a reasonable choice). This helps readers navigate between versions of our various docs that are mutually supportive. However, it can be difficult to track down and fix discrepancies in the 3,000+ page Unity manual.

The Package Documentation Link Report tool examines a branch of the Unity source, examines links in the branch's documentation markdown files, and compares the versions of the links to the Editor manifest in the same branch. The report indicates whether the documentation link is behind, the same, or ahead of the manifest version (or if the link uses @latest).

Note

There can be valid reasons to link to older package versions in some cases. For example, a feature no longer supported might still have a use for some customers, in which case, directing them to an older version that still supports that feature might be the best we can do for them.