[api-extractor] Improve namespace support

[adventure-yunfei (adventure-yunfei)]

Fix Cases:

Currently this case won't work:

import { sub } from './sub';

// case 1: directly export "sub" module content
export { sub };

// case 2: export a namespace
export declare namespace NAMESPACE {
  export interface Foo {};
}

First, api-extractor cannot build correct api.json for case 1 (invalid name).
Second, while configure api-extractor.json to "namespaceSupport": "permissive", api-extractor successfully builds api.json, but api-documenter won't generate document for namespace.

What this PR does:

• fix api-extractor for sub module exports
• fix api-documenter for api reference search (for namespace case, api reference will be more than limited "package" -> "export name" -> "member name" hierarchy, and right now it's a quick fix which only affects api-documenter package )
• add namespace document support for api-documenter

[Microsoft Contribution License Agreements (msftclas)]

All CLA requirements met. #Resolved

[Pete Gonzalez (octogonz)]

Thanks adventure-yunfei (@adventure-yunfei) for submitting this PR! I will take a look soon. #Resolved

[Pete Gonzalez (octogonz)]

Alex Jerabek (@AlexJerabek) your group is the primary user of namespaces with API Extractor.

Before we merge this PR, could you test it against the Office Add-ins project to make sure it doesn't break anything?

My specific concern are the changes in AstNamespace.ts and DocItemSet.ts which affect the YAML pipeline. Thanks! #Resolved

[Alex Jerabek (AlexJerabek)]

Pete Gonzalez (OLD ALIAS) (@pgonzal) Just tested the changes against office-js. Nothing appears to be different in the yaml or json files. #Resolved

[Pete Gonzalez (octogonz)]

Thanks Alex Jerabek (@AlexJerabek) for taking the time to test this! I will merge it. #Resolved

[Pete Gonzalez (octogonz)]

[Pete Gonzalez (octogonz)]

adventure-yunfei (@adventure-yunfei) thanks again for contributing this fix!

[adventure-yunfei (adventure-yunfei)]

Pete Gonzalez (OLD ALIAS) (@pgonzal) I'm just using api-documenter for typescript project right now. Searched around the world and almost tried every ts doc generator, you guys wrote the cleanest codes. While some features are not supported yet, it's not quite hard for me to figure out the logic and implement them. Nice Work!

But at I said this fix is just a quick fix. With namespace, "package" -> "export name" -> "member name" hierarchy is not enough. A re-implementation of api reference may be needed~

[Pete Gonzalez (octogonz)]

Is your project open source? If so I'd be interested to see your API and documentation scenario.

We're going to be improving the analysis in our next sprint, by adapting the new .d.ts generator code to handle the .api.ts and .api.json features as well.

[adventure-yunfei (adventure-yunfei)]

It's an internal project, but I can describe a little bit. The required missing feature is the export statement support.

The directory hierarchy is:

• root/
  • math/
    • mathUtils/
    • Vector3.ts
  • events/
  • utils.ts

And the exported api file combines all of them.

// api.math.ts
import * as Vector3 from './math/Vector3';
import * as mathUtils from './math/mathUtils';
export { Vector3, mathUtils };

// - api.ts
import * as events from './events';
import * as math from './api.math';
import * as utils from './utils';
export { events, math, utils };

In this case the api reference for class Vector3 would be "" -> "math" -> "Vector3" -> "default" (and it could be deeper with nested namespace/es6-export-statement).

Some other missing features are:

• type support (const, type). Currently it seems to only support namespace/class/interface/...
• link support. Sometimes api link doesn't exist for properties, mostly in deep hierarchy, or some special syntax like typeof Foo['bar'];

If you need, I may re-create an example project.

[Pete Gonzalez (octogonz)]

Thanks, this is helpful! If you find the time and are able to create a small repro branch on GitHub that illustrates these issues, when I am working on the analysis engine I can try to make sure these cases are handled correctly. If not, I can try to infer it from these notes.

[adventure-yunfei (adventure-yunfei)]

I've made an example project that demonstrates what I've met before. Hopefully it'll help you.
https://github.com/adventure-yunfei/api-documenter-example-case