Flow: Exported functions should throw "Missing annotation" when return type is not annotated

[cvoege]

Currently if you export a function flow will require that you annotate the parameters so that it can use them when the functions are importing the function in other places. However, it does not require you to annotate the return value in the same way. The behavior should be consistent to guarantee that when you import a function flow knows what return type to expect from it.

[andreypopp]

I think flow doesn't require return type annotations only in case it can infer it. That means knows the type of values function can return even if you don't put annotations there.

[jeffmo]

Right, this is intentional: Flow infers the return type of functions -- even exported ones.

Note that Flow never infers any -- so if you export a function and Flow doesn't complain, it means that Flow has been able to prove to itself that there is no type error.

Of course you can always put return types on any function you want if you want to be more specific or just be explicit.

[cvoege]

@jeffmo Don't you think it's a good idea to require the return type too for consistency? It can infer the parameter types just as well but instead it yells at you to write them yourself if the function is exported. I like it when flow yells at me for those so I keep all exports annotated, but it doesn't yell at me for the return types which means i forget to annotate them a lot. That's not exactly a problem, but I think it's smart for consistency sake.

[samwgoldman]

There's an ESLint plugin that will enforce this: https://www.npmjs.com/package/eslint-plugin-flowtype

[cvoege]

@samwgoldman I have that plugin, though the rule will be enforced on every single function (with a rule to disable it for arrow functions), when I think what's important here is that flow itself does it on exported functions for consistency with parameters.

[jeffmo]

@cvoege: it should be possible to extend a linter (perhaps the aforementioned one would be amenable?) to enforce this requirement only on exported functions (if you're using ES exports, at least).

In general I don't know that everyone would agree that requiring return types is necessary -- so while I think it's a perfectly reasonable style for a codebase, it's not something that we'd want to push on everyone.

As for why we require annotations on other aspects of exported things: It's really a way to help make Flow performant and efficiently parallelizable. It turns out that requiring return types on exported functions doesn't really do much to serve that purpose, and some prefer to leave them off, so we just leave these kinds of things to per-codebase style enforcement like linters instead.

[singpolyma-shopify]

are argument annotations really required on every exported function? That seems pretty heavy-handed to me...