Flow type imports syntax is not enough to have module documented

[tibdex]

Hi,

I'm trying to use documentation.js 4.0.0-beta.18 with Flow and it's working pretty well for infering types. However, my code is spread across several modules and I would like to use the Flow type imports syntax like this:

// index.js
// @flow
import type {MyNumber} from './types';

/**
 * My number
 */
const myNumber: MyNumber = 1;

// types.js
// @flow

/**
 * My number type
 */
type MyNumber = number;

export type {
  MyNumber
};

Here is the page generated by documentation.js:

But instead I would expect:

Where MyNumber type is added to the documentation.

If I change index.js like this:

 // @flow
+import './types';
 import type {MyNumber} from './types';

Then I'll have the result of the second image.

So to me, it seems like an import type statement is not enough to have documentation.js look up the content of the imported module.

Can we add support for this import type syntax into documentation.js ? If yes, do you have an idea of where should I start if I wanted to change the actual behaviour and submit a PR ?

Thanks!

[tmcw]

Sure, so here's what's currently happening:

• we use module-deps to document required & imported code as well as the main entry points
• and use babelify with it to handle import syntax and other ES6+ syntax

it's all good so far but

The import type syntax doesn't transpile to require or equate to import - babel removes it entirely. So when someone uses import type, module-deps doesn't catch it because babel doesn't output it.

The solution is... I'm not totally sure. I think the fastest fix would be a babel plugin that does output import type statements. Maybe there's another potential solution?

[tibdex]

Thanks for the explanations Tom!

Indeed, Babel removes the import type syntax but it's because the react preset is enabled and it comes with the transform-flow-strip-types plugin. If instead of relying on the react preset we would depend on all its plugins except from transform-flow-strip-types the import type would still be there.

The list of plugins that would have to be added as dependencies of documentation.js instead of babel-preset-react is:

• babel-plugin-syntax-jsx
• babel-plugin-transform-react-display-name
• babel-plugin-transform-react-jsx
• babel-plugin-transform-react-jsx-source
• babel-plugin-transform-react-jsx-self
• babel-plugin-syntax-flow

I can imagine that additional transform plugins could be added in future releases of babel-preset-react and thus we might not want to have to maintain this list.

However, I assume documentation.js actually only needs the plugins that make JSX and Flow syntax parseable by Babel and is not concerned with these transform plugins since they do not impact the documentation. Am I right ? Then the list would just be babel-plugin-syntax-jsx and babel-plugin-syntax-flow and I don't see it changing any time soon.

Do you think replacing babel-preset-react by babel-plugin-syntax-jsx and babel-plugin-syntax-flow is a good idea ? If I were to submit a PR to do it, would you be willing to merge it ?

[tibdex]

I tried to do the changes mentioned above but if we don't strip Flow syntax such as const myNumber: MyNumber = 1; then module-deps is not able to parse the module.

One other way to do it would be to split transform-flow-strip-types into two plugins. One would strip the import type syntax and the other would handle the rest. However I think it's becoming too convoluted.

Instead, I'll use the shorthand import syntax introduced in Flow 0.38.0. Feel free to close the issue if you consider that this is a satisfying solution.

[tmcw]

So, I think even if you're able to remove Flow syntax, module-deps will still not get the dependency chain afaik. module-deps operates on ES5 JavaScript source and only detects require() dependencies, not import or import type or any other kind of import, and it relies on Babel to transpile import into require in order to do that.

I'd definitely consider replacing module-deps with something that parses ES6 and/or uses Babel, but I haven't been able to find anything that does.

[arv]

For document-exported we follow imports. It is not too hard. We could extract that code to be usable here.

[andrewcharnley]

Also experiencing this issue.

How about a babel plugin (or similar) which copies the import type to a comment underneath it, which babel won't remove, then it's scanned by documention.js?

[tmcw]

Sure, that'd be a workable solution if someone wants to work on it.