Comments (25)
IMO, it would be great if Flow could take into account JSDoc declarations.
Because JSDoc already has semantics for user-types and arguments definition.
from flow.
@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.
from flow.
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.
from flow.
@avikchaudhuri Perhaps this needs to be reopened since #3 has been merged and closed, but without JSDoc support.
from flow.
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.
from flow.
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.
from flow.
Good idea, will look into this.
from flow.
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.
from flow.
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.
from flow.
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.
from flow.
Merging with #3
from flow.
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.
from flow.
Please read the merged ticket. Jsdoc docblock comments are explained there. They went with flowtate instead.
from flow.
There is also a problem that JSDoc won't event generate docs for code with flow annotations.
from flow.
@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
from flow.
@nmn ah, cool. Though last I tried gen-flow-files
/read about it in the changelog it was a pretty buggy, preliminary implementation.
from flow.
@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.
from flow.
@jedwards1211 - documentation.js has native support for flow notation
from flow.
@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...
from flow.
@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!
from flow.
In my point of view, the most useful workflow is:
- Conditionally parse
jsdoc
for types (off by default) - Generated stubs for this file with the parsed types
- 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?
from flow.
@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.
from flow.
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
from flow.
@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.
from flow.
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.
from flow.
Related Issues (20)
- Does not narrow down type after undefined/falsy check HOT 1
- Recursive/deep Partial HOT 2
- Bugs in negated `instanceof` expressions HOT 1
- [Question]: How to fix flowgen test after flow update HOT 3
- [Discussion]: Any plans to make Flow more interpopble with TS ecosystem? HOT 5
- Higher order type parameter support HOT 1
- Readme links to 404
- Strange index signature error if you use $Keys<O> instead of the equivalent literal union inside $ReadOnlyArray HOT 1
- [homebrew] automation script needs update HOT 2
- "Unxepcted identifier, expected the token ;" when using await inside of ES module HOT 3
- Can't iterate through chars in a string HOT 4
- Flow does not catch invalid switch statements HOT 1
- Conditional type only works if I inline it HOT 5
- Object with null prototype does not extend interface {} HOT 3
- Missing documentation for "render-types"? HOT 2
- Relay + graphql literals HOT 11
- [homebrew] regression test failure with 0.226.0,0.227.0 HOT 2
- FLOW BUG: This is a misplaced error HOT 3
- The `experimental.ts_syntax` doesnโt seem to do anything HOT 2
- Parameters<> does not support optional params HOT 2
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. ๐๐๐
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google โค๏ธ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from flow.