Flow: relationship with JSDoc?

[stevemao]

It would be great if the readme or wiki states the differences/similarities between JSDoc (or any other tools) and flow. Thanks

[StoneCypher]

They are effectively unrelated.

Flow scans your source and looks for type errors that it knows aren't right. For example, if you make a function which does arithmetic, then pass a string to said function, flow will notice that.

[glukki]

IMO, it would be great if Flow could take into account JSDoc declarations.
Because JSDoc already has semantics for user-types and arguments definition.

[briandipalma]

It would be nice if JSDoc was parsed by flow and used as means to fill out type annotations for code that is missing them. It would help if there was a standard JSDoc format, I think the last time this was brought up at TC39 it was deemed not something that they should look at.

Maybe if tools like flow decided on one then other tools will standardize around it.

[avikchaudhuri]

Good idea, will look into this.

[Raynos]

It should be strongly noted that the semantics of JSDoc type system and flow type system are different.

Even if you can parse JSDoc, you may end up with ambiguity or with the problem that JSDoc cannot express enough information to get flow to check properly.

[avikchaudhuri]

Merging with #3

[cletusw]

@avikchaudhuri Perhaps this needs to be reopened since #3 has been merged and closed, but without JSDoc support.

[ianwsperber]

I agree with @cletusw that this issue should be reopened. Being able to use comments for flow types is very nice, but being able to use JSDoc syntax would make flow easily available to existing codebases. Also I still like writing JSDocs to document my functions regardless of the typing benefit, so it seems like it would be duplicate work to have both comment types.

[StoneCypher]

Please read the merged ticket. Jsdoc docblock comments are explained there. They went with flowtate instead.

[mhagmajer]

There is also a problem that JSDoc won't event generate docs for code with flow annotations.

[cameron-martin]

I think it would be useful to have a tool to generate/augment JSDoc annotations using flow's typechecker, rather than doing it the other way round. This way, documentation could be generated using JSDoc's documentation generator, but using flow's way more reliable type information.

[tonygentilcore]

I was looking for something similar and stumbled upon https://github.com/Kegsay/flow-jsdoc . Thought I'd leave it here in case it's useful to anyone.

[jedwards1211]

The thing that frustrates me is that the syntax for @param types in JSDoc is different than in Flow. I'd rather be able to put Flowtype types in my JSDoc, or that someone create a new documentation format altogether that's based upon Flowtype.

[nmn]

@jedwards1211 I think a proper flow-types codebase and the gen-flow-files command can just replace JSDoc altogether for types.

And, Documentation.js understands Flow so we shouldn't need JSDoc at all.
https://github.com/documentationjs/documentation/blob/master/docs/GETTING_STARTED.md#flow-type-annotations

[jedwards1211]

@nmn ah, cool. Though last I tried gen-flow-files/read about it in the changelog it was a pretty buggy, preliminary implementation.

[nmn]

@jedwards1211 Yeah gen-flow-files is still experimental, but at least its being worked on. I don't think JSDoc understanding has as much utility. Using JSDoc to add types is way less expressive than using Flow. At best, Flow should just treat leading comments before Functions as documentation. The type information doesn't belong in JSDoc.

[StoneCypher]

@jedwards1211 - documentation.js has native support for flow notation

[davidrapin]

@nmn the fact that you believe that "type information doesn't belong in JSDoc" might not be relevant here.
Most JS projects use JSDoc for type annotation, because that's how you get your IDE to become helpful. That's just a fact, things are done that way, whether we think its the right way or not.

The TypeScript complier added the ability to parse JSDoc annotation some time ago, and it makes a lot of sense: pure JS projects that had JSDoc type annotations are now able to be validated by the TypeScript compiler. That's a huge step forward.

It would be great to see Flow do the same.

[jedwards1211]

@davidrapin that's cool, but I bet there ended up being a lot of accidental errors from that approach? Because I would assume the types in a lot of JSDoc, being unchecked by a tool like Flow or TypeScript, tend to have a lot of mistakes...

[davidrapin]

@jedwards1211 Indeed, very good point. It induced some JSDoc-cleanup sessions on projects I'm involved with, but nothing we couldn't manage. It was worth it!

[sobolevn]

In my point of view, the most useful workflow is:

1. Conditionally parse jsdoc for types (off by default)
2. Generated stubs for this file with the parsed types
3. User can modify these stubs as usual

What advantages I see here:

• Possibility to fix wrong types declared in the docs
• Nothing will break by default (as it should not break because of the comments)
• We can still use existing type information

Do you see any cons in this solution?

[jedwards1211]

@davidrapin also, IDE support for flow type information was just behind relative to JSDoc because JSDoc came earlier. I'm pretty sure that WebStorm already understands flow types just as well as JSDoc, though I'm not sure. So JSDoc won't be the most ideal tool for IDE comprehension for long.

I think what @nmn means is that types for typechecking purposes don't belong in JSDoc.

[StoneCypher]

What they're talking about is pulling the flow types into the docs so that humans can read them, not so that the documentation checker can evaluate them

it's so that we don't have to type * @param foo {type} - bar when that's already known

[jedwards1211]

@StoneCypher I was referring to what David said, which I think other folks are advocating against:

The TypeScript complier added the ability to parse JSDoc annotation some time ago, and it makes a lot of sense: pure JS projects that had JSDoc type annotations are now able to be validated by the TypeScript compiler. That's a huge step forward.
It would be great to see Flow do the same.

[StoneCypher]

My response quite clearly expresses an understanding of that.

The reason that basically every documentation generator except this one supports at least one of the type systems at this point is that nobody wants to duplicate that information for their documentation.

Please re-read what I said to you, @jedwards1211. People should not be pushing back against this based on a faulty understanding of what's being requested.

There is a reason that every other documentation generator does this.