Relay: Documentation graphql.experimental

[sibelius]

• [ ] valid directives (arguments, @argumentDefinitions)
• [ ] use cases

and so on

[wincent]

Ideally, those use cases would be documented when experimental is no longer, er, experimental. Part of the reason — actually, the entirety of the reason — for even having graphql.experimental at all is because we wanted to create a space in which to isolate features/semantics which might be subject to change in the future (including even the possibility of removing them!) and so we wanted to avoid documenting them to minimize downstream pain.

Having said that, I think it's more likely that @arguments and @argumentDefinitions are here to stay than that they'll be removed. We wanted to see how straightforward it would be to port existing big Relay Classic apps at FB to Relay Modern without it, but we've found a number of cases where it feels better to use @arguments/@argumentDefinitions than to forgo it.

Maybe the question we should be asking is not, "should we document graphql.experimental?", but "should we graduate specific features to non-experimental status?"

[sibelius]

this file is a good starting point for @argumentDefinitions

https://github.com/facebook/relay/blob/6cd00fa45f78c0ae1580800f6e4ee40881e1f399/packages/relay-compiler/core/RelayCompilerScope.js

[tim-field]

This is quite confusing as experimental is part of the main documentation ( yet it has no introduction or explanation )
https://facebook.github.io/relay/docs/refetch-container.html

[sibelius]

Check this out: https://medium.com/@sibelius/relay-modern-argumentdefinitions-d53769dbb95d?source=linkShare-fdf9efd749e0-1503877554

[MatthewHerbst]

What's especially confusing is that this is being used in official documentation, without any note of what they are, and without any note of graphql.experimental:

https://facebook.github.io/relay/docs/refetch-container.html

Gives an incredibly cryptic error considering there are no docs for it:

Parse error: Error: Unexpected use of fragment variables: @arguments and @argumentDefinitions are only supported in graphql.experimental literals.

[robrichard]

@MatthewHerbst prior to v1.4.0 @arguments and @argumentDefinitions required that you use graphql.experimental tagged template literals instead of the standard graphql. graphql.experimental has since been deprecated so the docs were updated. I have a PR open to add more docs here: https://github.com/facebook/relay/pull/2177