New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
relationship with JSDoc? #43
Comments
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. |
IMO, it would be great if Flow could take into account JSDoc declarations. |
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. |
Good idea, will look into this. |
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. |
Merging with #3 |
@avikchaudhuri Perhaps this needs to be reopened since #3 has been merged and closed, but without JSDoc support. |
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. |
Please read the merged ticket. Jsdoc docblock comments are explained there. They went with flowtate instead. |
There is also a problem that JSDoc won't event generate docs for code with flow annotations. |
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. |
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. |
The thing that frustrates me is that the syntax for |
@jedwards1211 I think a proper flow-types codebase and the And, Documentation.js understands Flow so we shouldn't need JSDoc at all. |
@nmn ah, cool. Though last I tried |
@jedwards1211 Yeah |
@jedwards1211 - documentation.js has native support for flow notation |
@nmn the fact that you believe that "type information doesn't belong in JSDoc" might not be relevant here. 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. |
@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... |
@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! |
In my point of view, the most useful workflow is:
What advantages I see here:
Do you see any cons in this solution? |
@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. |
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 |
@StoneCypher I was referring to what David said, which I think other folks are advocating against:
|
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. |
It would be great if the readme or wiki states the differences/similarities between JSDoc (or any other tools) and flow. Thanks
The text was updated successfully, but these errors were encountered: