Comments (17)
I have confirmed the possibility and I will add it tomorrow. It is a very good suggestion, thank you.😀
from async-graphql.
I have completed this feature and updated the example code of starwars
. 😁
https://github.com/async-graphql/examples/tree/master/models/starwars
from async-graphql.
Please upgrade to version 1.11.0, which already contains this feature.😁
from async-graphql.
Let me think about this wapper, I first add the use_type_description
attribute.
from async-graphql.
I'm not sure rust's procedural macros support this, but I'll add them if possible. 😁
from async-graphql.
I am very excited. Repeating the description twice is too annoying. It is very convenient to get the desc directly from rustdoc.
from async-graphql.
@sunli829 is it also possible to use the structs rustdocs? See the example below.
#[derive(Deserialize, Debug)]
/// A company is a legal entity representing an association of people, whether natural,
/// legal or a mixture of both, with a specific objective/goal.
pub struct Company {}
#[Object]
impl Company {
/// Globally unique identifier of a company.
pub async fn id(&self) -> &ID {
todo!()
}
/// The company name.
pub async fn name(&self) -> String {
todo!()
}
}
Docs are currently only generated if i add the rustdocs to impl Company
, but that would make it necessary to duplicate the docs on the struct
and on the impl
, because docs on the impl
are not shown in the IDE.
And another question, is it possible to add docs to a generated ...Connection
and a ...Edge
? And...is it possible to modify the docs of scalars that are delivered with async-graphql
, for example, can i as a user of the crate modify the docs of DateTime
?
from async-graphql.
I suppose for the first one we could add a derive macro Description
or something that derives a trait
trait Description {
fn description(&self) -> &'static str;
}
And we could either have #[Object(use_type_description)]
where it uses that trait, or the other way around where no docs on the impl assumes that it implements Description
, and you'd have to write #[Object(no_docs)]
to disable that.
For the second one we could either:
- Make it easier to make type wrappers
- Provide a method on the schema which overrides type descriptions (e.g.
Schema::build(q, m, s).override_description::<DateTime>("custom datetime docs")
) - Use the inventory crate and provide a macro like
override_docs! { /// custom datetime docs DateTime }
from async-graphql.
Hm...for the second one, i think i would like the macro override_docs!
best, if it also changes the docs that pop up in the IDE.
The first one, the trait, i think that won't work with IDE docs. I would really like to not need to replicate the docs from the struct
to the impl.
To make it more clear, i will reuse but shorten the previous example:
With the following code, i get the docs shown by the IDE as a popup, see screenshot, but not in graphql.
#[derive(Deserialize, Debug)]
/// A company is a legal entity representing an association of people, whether natural,
/// legal or a mixture of both, with a specific objective/goal.
pub struct Company {}
#[Object]
impl Company {
/// Globally unique identifier of a company.
pub async fn id(&self) -> &ID {
todo!()
}
}
When i put the docs on the impl
, then they are shown in graphql, but not in the IDE.
#[derive(Deserialize, Debug)]
pub struct Company {}
#[Object]
/// A company is a legal entity representing an association of people, whether natural,
/// legal or a mixture of both, with a specific objective/goal.
impl Company {
/// Globally unique identifier of a company.
pub async fn id(&self) -> &ID {
todo!()
}
}
Ideally, docs that are on the struct should be used for graphql too.
from async-graphql.
So what I meant for the first one is that you'd write:
#[derive(Deserialize, Debug, async_graphql::Description)]
/// A company is a legal entity representing an association of people, whether natural,
/// legal or a mixture of both, with a specific objective/goal.
pub struct Company {}
#[Object(use_type_description)]
impl Company {
/// Globally unique identifier of a company.
pub async fn id(&self) -> &ID {
todo!()
}
}
And in the expansion it would write:
description: Some(<Self as ::async_graphql::Description>::description()>),
if it also changes the docs that pop up in the IDE.
No, it won't - there is no way to change the actual Rustdoc attributes of another item. All that macro does is to add that doc string to a global list of doc strings for that type, so when you register the type in the schema it uses the global list of doc strings. I don't really like that solution because inventory
is a bit of a hack.
from async-graphql.
Ah...i misunderstood you. I am not really deep into the howto's of macros, so maybe the my question is somewhat silly. Currently, the Object macro reads the rustdocs of wherever it is put on? Can a macro read the rustdocs of another struct or is it restricted to where it is placed?
No, it won't - there is no way to change the actual Rustdoc attributes of another item.
Then i think scalarwrapper is the way to go. If you can simply wrap the priovidedDateTime
, maybe like this
#[derive(ScalarWrapper)]
/// My super doc comment.
pub struct MyDateTime(DateTime);
then one would easily get both, the IDE popup when working with that struct and the GraphQL docs. Ideally, the macro should use the name of the inner type for the graphql type, or at least make renaming possible. Maybe even two different wrapper macros, for a specific purpose.
A ScalarDocsWrapper
for just changing the docs, which then uses the name of the inner type for generation.
And a ScalarWrapper
that allows renaming and also changing the docs. Dunno if that really makes sense. Just some thoughts.
from async-graphql.
Currently, the Object macro reads the rustdocs of wherever it is put on?
Yes
Can a macro read the rustdocs of another struct or is it restricted to where it is placed?
No, this is why we have to add another derive macro and use the trait to communicate between the two.
I don't really like the ScalarWrapper
name, but I don't have any other suggestions. @sunli829, what do you think?.
from async-graphql.
I think this looks better. 😂
#[derive(Deserialize, Debug, async_graphql::Description)]
/// A company is a legal entity representing an association of people, whether natural,
/// legal or a mixture of both, with a specific objective/goal.
pub struct Company {}
#[Object(use_type_description)]
impl Company {
/// Globally unique identifier of a company.
pub async fn id(&self) -> &ID {
todo!()
}
}
I think there is no need to add a wrapper type just to be able to shown the document in the IDE, which will cause more trouble.
from async-graphql.
@Koxiaet Thanks for clarifying!
@sunli829 The wrapper would be for overriding the docs of scalars that exist inside of async-graphql
, like ID
or DateTime
.
from async-graphql.
@sunli829 The wrapper would be for overriding the docs of scalars that exist inside of
async-graphql
, likeID
orDateTime
.
Ah, this seems to be useful.
from async-graphql.
Oh...i think we missed one, what about the generated ...Connection
and a ...Edge
types? Is it possible to add GraphQL docs to them?
from async-graphql.
While we are at it 😄 : I have been meaning to verify this as of v2.0.0, but if I recall correctly, graphql docs were not generated for enum variants and custom scalars. Is that still true?
from async-graphql.
Related Issues (20)
- Has anyone does any benchmarks because im getting extremely poor results and I do not know why? HOT 8
- Get mutable referenece to the global data defined in the `Context` or `Schema` HOT 1
- Confusing `unused_mut` warning in `#[Object]` HOT 8
- How to handle both directions of one-to-many relation in federated graph
- Question: How to get server to send ping messages on subscriptions? HOT 2
- Parsing multiple operations in a file HOT 1
- Non nullable variables should allow default values HOT 3
- Object with single skipped field but with ComplexObject HOT 2
- As using proxy type
- Using flatten inside an impl with no other fields causes a compile error
- Subscription with MPSC receiver in context data
- Reduce clippy noise from #[Object] macro HOT 2
- Guard trait lifetime HOT 1
- Using generics with both SimpleObject and InputObject as field in output type fails HOT 1
- Subscription Authentication
- Stack overflow after upgrade to 7.0.2 HOT 5
- Does async-graphql validate responses?
- Error reading data from ExtensionContext after upgrade to 7.0.3 HOT 1
- Create a general error formateer
- Allow flatten on arguments 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 async-graphql.