Partial attempt at adding nullable reference annotations (#4007) - #6461

I'm using docfx in one my libraries, and finally got around to digging into why nullable reference annotations aren't included in the generated YAML/HTML. I see there's an old-ish issue (#4007) that mentions this as well.

This is a draft because, well, it's not finished. For the life of me I cannot figure out why what's ending up in the YAML isn't ended up in the generated HTML (using the default template). I would like to finish this work and submit a proper PR, but after a couple days of false starts I'm hopeful someone more familiar with the code can tell me what I'm missing.

Where things are, concretely.

I currently have one test case, and it's generating "correct enough for now" YAML - specifically in MetadataItem.Syntax.Content. I suspect there are are still some real issues, and there are definitely still some TODOs - but things are far enough along for me to try testing on my library.

However, when I do test against my library I get the new YAML but not the HTML I'm expecting.

Example:

For a declaration like so (source):

public static IAsyncEnumerable<TRow> EnumerateAsync<TRow>(
            TextReader reader,
            Options? options = null,
            object? context = null,
            CancellationToken cancel = default
        )

I'll get a chunk of YAML including (full chunk in this gist):

  syntax:
    content: public static IAsyncEnumerable<TRow> EnumerateAsync<TRow>(TextReader reader, Options? options = null, object? context = null, CancellationToken cancel = null)

But the HTML is

  <h5 class="decalaration">Declaration</h5>
  <div class="codewrapper">
    <pre><code class="lang-csharp hljs">public static IAsyncEnumerable&lt;TRow&gt; EnumerateAsync&lt;TRow&gt;(TextReader reader, Options options = null, object context = null, CancellationToken cancel = null)</code></pre>
  </div>

Which looks like so:

I'm building docfx with the following command:
.\build.ps1 -skipTests -configuration Debug

And pulling out what ends up in \bin\Debug\. I did see there's a target directory that gets built too, but trying its contents has made no difference either.

Cesil's docfx.json is in its repo, but I'll reproduce it here.

{
  "metadata": [
    {
      "src": [
        {
          "files": [
            "Cesil/Cesil.csproj"
          ]
        }
      ],
      "dest": "api",
      "disableGitFeatures": false,
      "disableDefaultFilter": false
    }
  ],
  "build": {
    "globalMetadata": {
        "_enableSearch": false,
        "_disableToc": true
    },
    "content": [
      {
        "files": [
          "api/**.yml",
          "api/index.md"
        ]
      }
    ],
    "resource": [
      {
        "files": [
          "images/**"
        ]
      }
    ],
    "overwrite": [
      {
        "files": [
          "apidoc/**.md"
        ],
        "exclude": [
          "obj/**",
          "docs/**"
        ]
      }
    ],
    "dest": "docs",
    "globalMetadataFiles": [],
    "fileMetadataFiles": [],
    "template": [
      "default"
    ],
    "postProcessors": [],
    "markdownEngineName": "markdig",
    "noLangKeyword": false,
    "keepFileLink": false,
    "cleanupCacheHistory": false,
    "disableGitFeatures": false
  }
}

Poking around and liberally dropping breakpoints, best I can tell the syntax bits from the YAML are being loaded up correctly. Something is obviously off... somewhere - my gut tells me I've either messed up a build step, or am missing somewhere where syntax is transformed in the default templates (which would imply I need to either change a template, or update additional fields in the YAML).

Any guidance on what I'm missing?

Microsoft Reviewers: Open in CodeFlow