Comments (11)
This is a great idea and we definitely want to explore this. One issue is that we would want support for multi-line strings and markdown so we would need to think about how to incorporate that
from graphql-js.
@schrockn do you have some ideas how those multiline strings could look like?
The example I posted reuses the directive syntax from GraphQL documents. One option could be to keep that syntax, but let the arguments to be multiline strings (a new construct), e.g.:
type User {
stories: StoryConnection
@meta(
description: "All stories authored by the user."
examples: """
Here are some examples written in markdown.
You can use all the normal arguments.
```
stories(first: $first) { nodes { text } }
```
etc.
"""
deprecationReason: "You should not use this anymore."
)
}
Or used with separate directives for all these (argument names make this a bit noisy):
type User {
stories: StoryConnection
@description(text: "All stories authored by the user.")
@examples(text: """
Here are some examples written in markdown.
You can use all the normal arguments.
```
stories(first: $first) { nodes { text } }
```
etc.
""")
@depracated(
reason: "You should not use this anymore."
sinceDate: "2015-08-11"
)
}
I think the benefit of this approach is that it allows more information to be easily added in the later versions through new directives or new arguments for existing directives. It also borrows the syntax from queries, so there's no new syntax to be learned or implemented besides multiline strings.
from graphql-js.
The annotation syntax is a good idea. I definitely think descriptions should have the simplest possible syntax. We should treat those in a first-class way since they are so pervasive.
Maybe we should investigate doing something similar to literate coffeescript
from graphql-js.
I changed the syntax a bit to move the field directive before the field it applies to. I think this is more readable and also familiar from JS decorators, Java annotations etc.
There is now a pull request that implements directives for fields in type definitions: #180. Please let me know what you think.
from graphql-js.
from graphql-js.
Might you consider putting annotations inside multi-line comments?
type User {
"""
User documentation goes here. Easy to write __Markdown__ here?
If someone wanted to extend the ability of comments, they could. Maybe a sort of doctest?
"""
stories: StoriesConnection
"""
Maybe you could associate this comment with a the stories field. Or should it come before?
@deprecated: on 11-11-15 for whatever reason.
"""
other: Int # These comments could stay associated too
}
Just an idea. Obviously inspired by Python.
from graphql-js.
@abuchanan Yeah, also look at @leebyron's suggestion using the existing single-line comments: #180 (comment). I think it could be a nice way to add them without introducing additional syntax.
I experimented a bit with adding annotations inside comments. The only problems were that the parser then needs to be made aware of comments everywhere (at the moment it discards them at the lexing stage), making parsing more complex, and distinguishing description comments from other comments. Parsing should be smart enough to handle cases like this:
# This source code is licensed under the BSD-style license found in the
# LICENSE file in the root directory of this source tree. An additional grant
# of patent rights can be found in the PATENTS file in the same directory.
# (This is not a description for Foo)
type Foo implements Bar {
# Random note
# Description for `name`
name: String
}
Still, I think utilizing comments would probably be the simplest way to add annotations.
from graphql-js.
Even if you want to use annotations instead of comments, please make sure one can read comments from parsed schema. Otherwise information is lost after parse -> print cycle.
from graphql-js.
@fson I just wrote up a related proposal for adding metadata to schemas here: https://github.com/apollostack/graphql-decorators/blob/master/README.md
It needs some more work, but it would be great to get your input. I'm hoping that if we all agree on something, a successful PR can be made.
from graphql-js.
Committed in #382 - thanks for starting this!
from graphql-js.
Awesome, thanks! 👍
from graphql-js.
Related Issues (20)
- IHeyReally.org
- Suggestion: Bundling in v17, ESM, CJS, and the dual package hazard HOT 9
- Just to give my 2c, I'm not sure if `exports.development` and `exports.production` target conditionsa are widely supported, so some `import.env` shenanigans may still be necessary until that's widely adopted. HOT 1
- Collection of libraries and how they import from `graphql` HOT 20
- `process.env`, `globalThis`, and `typeof process` HOT 21
- Introspection queries don't support `@oneOf` HOT 2
- Tutorial data HOT 2
- astFromValue fails with a custom scalar serializing to an object value HOT 5
- In a response to a query about an Issue, the URL and other info is missing for links created with Reference editor button HOT 5
- author/committer -> user fields returning NULL for commits committed by user
- [email protected]
- npm link with graphql package breaks application HOT 2
- IHeyReally.com HOT 1
- Can I ask what is the progress here? Is there a solution being worked on? Do we have some timeline? Or progress with issue? Thanks!
- IHeyReally.com
- Typescript error with 16.9.0 (re ThunkObjMap) HOT 3
- Notice: default branch is now `16.x.x` HOT 2
- <a href="https://api.easycla.lfx.linuxfoundation.org/v2/repository-provider/github/sign/12261526/38307428/4135/#/?version=2"><img src="https://s3.amazonaws.com/cla-project-logo-prod/cla-not-signed.svg" alt="CLA Not Signed" align="left" height="28" width="328"></a><br/><br /><ul><li><a href='https://api.easycla.lfx.linuxfoundation.org/v2/repository-provider/github/sign/12261526/38307428/4135/#/?version=2' target='_blank'>:x:</a> - login: @Heyitsquoracom / name: [email protected] . The commit (b6081f914f0c5c22ee48d26aff4b473bf17627ce) is not authorized under a signed CLA. <a href='https://api.easycla.lfx.linuxfoundation.org/v2/repository-provider/github/sign/12261526/38307428/4135/#/?version=2' target='_blank'>Please click here to be authorized</a>. For further assistance with EasyCLA, <a href='https://jira.linuxfoundation.org/servicedesk/customer/portal/4' target='_blank'>please submit a support request ticket</a>.</li></ul><!-- Date Modified: 2024-06-28 04:40:51.630768 -->
- Error with version v16.9.0: `Can't resolve '@apollo/subgraph/dist/directives''` HOT 1
- Type is incorrect in graphql ExecutionResult with new type GraphQLFormattedError HOT 1
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 graphql-js.