Documentation improvements

[MichalLytek]

The documentation was written a bit carelessly because that time I was focusing on iterating with code and features. Also my English is rather on B2/C1 level. That's why there might be some typos and grammar mistakes 😞

So I would like to ask the community to get involved in this project and help making TypeGraphQL great ~again~ at least 😄 If you found a typo or other mistake in docs, feel free to report it or even create a PR with fix for that!

Also, there are some voice that some design goals and architectural choices that I've made are a bit non-intuitive:

sometimes, it's good to have documentation being written by someone else or at least being updated by a person who is not an author of the library and don't have full knowledge about why given design decision have been made

So if you find something like that - also feel free to report that. I will try to clarify it and improve the docs or maybe it might be a good point for a new feature?

Thank you, guys! Let's contribute and celebrate Hacktoberfest! 🎉

[MichalLytek]

https://github.com/19majkel94/type-graphql/issues/51#issuecomment-431506866

I see that for top level queries Vesper has Controllers, and Resolvers only for custom types. I find it a little bit more intuitive, especial for newcomers. So I think it would be nice to have better explanation in docs how typegraphql's API correlates with standard GraphQL one. Just at the beginning it wasn't super intuitive for me, but as I've started using it, it makes much more sense now.

At the beginning TypeGraphQL aimed for apollo-ecosystem users, like graphql-tools, were you create resolvers map for your queries, mutation and object types. Also, I've designed it to fix all the issues that I've found using that stack.

In GraphQL specification there's no distinction between User and Query - there are both ObjectType, so there are created in the same way using graphql-js library. So for GraphQL users it might be weird if I would separate query resolvers from object type resolvers by naming it "controllers".

I know that "controllers" might be more intuitive name for people that comes from HTTP frameworks like Spring, routing-controllers or Nest. But even in Nest you have resolvers that encapsulate all the GraphQL logic related to a scope, like an User - all queries and mutation that are related to User + it's field resolvers: https://docs.nestjs.com/graphql/resolvers-map

There's no technical obstacles to separate controler-like class from field-resolver-like class. You can do this now and name it whatever you want, like UserControler. There might even a decorator @Controller as an alias for @Resolver but this distinction would force to introduce a separate property in schema config, like:

await buildSchema({
  resolvers: [UserResolver],
  controllers: [UserController],
});

Which I think is a bad idea as it over complicates things. There's already a note about the resolvers to controllers relation:

At first, you have to create a resolver class and annotate it with @Resolver() decorator. This class will behave like a controller known from classic REST frameworks.

But we can make this paragraph a bit more clear 😉

[j]

Eeks, I've never considered a GraphQL resolver to be a controller. GraphQL !== MVC. GraphQL === GraphQL. :P

[conartist6]

Yeah that really threw me. All the examples are of thing's I consider inappropriate usages of GraphQL. I would strongly recommend that you choose an examples where you at very least have types that have relationships to each other. For example I can't understand how to create a type definition that includes calls. Your documentation suggests that resolvers, which you liken to controllers, have calls with arguments, and models don't. But while that's how MVC works it isn't how GraphQL works.

[MichalLytek]

@conartist6 I quite don't understand what you are talking about. Mainly, what is "a type definition that includes calls"? 😕

choose an examples where you at very least have types that have relationships to each other

You have many relations in TypeORM example. Simple examples only demonstrates simple features, like deprecations, descriptions or authorization.

So please, rewrite your sentences to a more understandable English and maybe add some examples, background of what you were trying to achieve, etc.

[jeremyong]

One documentation bug I noticed is that the Getting Started page references a "RecipeService" in the constructor of the sample resolver, but I can't find where this is defined (except to infer what it is based on the usage)

[MichalLytek]

@jeremyong Because it's a getting started, short guide, so its implementation give no valuable info in the context of TypeGraphQL - it's just an injected class instance which works like a group of CRUD methods which you can infer from the usage.

[exaucae]

I now think #1206 fits there.