[api-extractor] Namespace-level objects getting dropped

[AlexJerabek]

Objects created at the namespace level are not captured by API-Extractor. In the following example, we'll see Office in the json files, but not context.

declare namespace Office {
    var context: Context;
}

Source d.ts

[octogonz]

This will be fixed in AE7. I'll share the PR branch as soon as it's ready. It's 95% code-complete.

[octogonz]

(This assumes that the documentation system's YAML schema supports exported variable declarations.)

[AlexJerabek]

Awesome. Thanks @pgonzal! I figured this was coming, but wanted an official issue tracking it.

[octogonz]

In PR #951 this is now working for *.api.ts and *.d.ts rollups. But it's not yet wired up to the documentation pipeline.

[octogonz]

Could you retest this with the latest API Extractor (7.0.17)? I believe is fixed now.

Also, I believe the declaration needs to have an "export" statement. Something like this:

export declare namespace Office {
    var context: Context;
}

[AlexJerabek]

Tested our doc-generation with the latest version. It looks like the namespace-level objects are showing up in the JSON.

{
              "kind": "Variable",
              "canonicalReference": "context",
              "docComment": "/**\n * Gets the Context object that represents [...]",
              "excerptTokens": [
                {
                  "kind": "Reference",
                  "text": "context"
                },
                {
                  "kind": "Content",
                  "text": ": "
                },
                {
                  "kind": "Reference",
                  "text": "Context"
                }
              ],
              "releaseTag": "Public",
              "name": "context",
              "variableTypeTokenRange": {
                "startIndex": 2,
                "endIndex": 3
              }
            },

However, I don't see a corresponding yml file produced through the API Documenter. Is there an updated version of that too? I'm currently running 7.0.19.

[octogonz]

@AlexJerabek The YAML generator currently doesn't handle variables:

YamlDocumenter.ts

  private _generateYamlItem(apiItem: ApiDocumentedItem): IYamlItem | undefined {
    // Filter out known items that are not yet supported
    switch (apiItem.kind) {
      case ApiItemKind.CallSignature:
      case ApiItemKind.ConstructSignature:
      case ApiItemKind.IndexSignature:
      case ApiItemKind.TypeAlias:
      case ApiItemKind.Variable:
        return undefined;
    }

The reason is that when this code was written the YAML file format did not have a way to represent these constructs. If they are supported, and you can provide an example of what the YAML object should look like, then it would be very easy to add support for them.

Since the general support is now working in the API Extractor engine, I'm going to reclassify this as an "enhancement" for now.