[api-extractor] Support "import * as __ from __" for local paths

[octogonz]

PR #1002 adds support for declarations like this:

import * as React from 'react';

This is a trivial implementation, where we pretend that * is an actual name exported by the "react" package. It does not work for the general form that introduces a new namespace, for example:

// For example, "Button" in controls.ts becomes "controls.Button"
import * as controls from './controls';

This form is called ts.SyntaxKind.NamespaceImport because it is essentially a more general form of the namespace controls { } declaration kind.

As such, it should probably produce an ApiItemKind.Namespace item.

[octogonz]

@gf3 shared a branch gf3/api-extractor-issue@30de59d that repros this issue.

[octogonz]

Some other examples were given in the comments for issue #663

[shlomiassaf]

@pgonzal I think that those imports should be handled differently, from a usage perspective and rather then semantic...

import * as React from 'react';
import * as controls from './controls';

export class ABC {
  p1: React.Component;
  p2: controls.Control;
}

The code above is similar to this:

import { Component }  from 'react';
import { Control } from './controls';

export class ABC {
  p1: Component;
  p2: Control;
}

The local import is purely semantic...
When generating docs it doesn't make sense to render p2: controls.Control; so the library should find the direct reference and ignore the namespace.

When importing from third party, it's a different story and the way it is rendered is up to the user, just need to make sure there's enough info...

[octogonz]

@shlomiassaf

FYI API Extractor wants all reachable types to have exported names, mainly for the software engineering reason that it's more difficult to use an API with anonymous types, and also more difficult for the documentation to talk about it.

For your second example, API Extractor should warn about Component, something like this:

import { Component }  from 'react';
import { Control } from './controls';

export class ABC {
  // WARNING: the declaration "Component" is not exported
  p1: Component;
  p2: Control;
}

Whereas in your first example, it should issue this sort of warning:

import * as React from 'react';
import * as controls from './controls';

export class ABC {
  // (no warning because the "React" module is an external package)
  p1: React.Component;

  // WARNING: the declaration "controls" is not exported
  p2: controls.Control;
}

If you mixed them, then the desired behavior is less clear:

import * as React from 'react';
import * as controls from './controls';
export { Control } from './controls';

export class ABC {
  // (no warning because the "React" module is an external package)
  p1: React.Component;

  // WARNING: the declaration "controls" is not exported
  p2: controls.Control;
}

I suppose the ideal behavior might be to realize that controls.Control is a synonym for Control and normalize it to eliminate the controls. part. But this is technically difficult. I haven't thought about it in depth because this problem seems to never occur in any of our code bases heheh.

[shlomiassaf]

@octogonz Thanks for clear explanation.

I think that the underlaying issue is more about the concept and direction of this project.
This tool is used for several tasks, document generation is one of them.

We can agree that generating documentation from the json output can happen is a lot of ways, so many that I can't count :)

At it's current state, the project does provide a way to change the behaviour, configuring it, etc...

Taking a lot of assumptions is risky because it means that it will only do and support things that occur in your code bases and that's not a very good approach for a public project.

I see great importance in tsdoc and this tool and I think that wide adoption will help the community because there are a lot of tools for this job, each with pros/cons and having a unified tool from MS is probably the best solution.

But, for that we need flexibility, understanding that your code base might not be the same as another's code base.

For example, let's say I built an angular library that uses a lot of symbols from various @angular libraries and also symbols from rxjs

Now of course all of them are not exported, but in my doc generator I can decide to generate links for them, based on some schema... links to the external documentation for these libraries...

So if a new ApiItem is created hosting the (not) exported symbol with it's package name, the doc generator can do the magic...

In angular it's a very simple schema: https://angular.io/api/[PACKAGE NAME]/[SYMBOL NAME]
Examples:

import { HttpHeaders } from '@angular/common/http';

https://angular.io/api/common/http/HttpHeaders

import { Component } from '@angular/core';

https://angular.io/api/core/Component

Usually, since documentation is auto-generated, a schema always exists...