Added getting started tutorial.

[LynxesExe]

This PR aims at providing a tutorial to ease people into getting started using cppgraphqlgen by explaining the "intended usage" of the project and the flow the users code has to follow.

The original comments related to this PR can be found here: #311 (comment)

[LynxesExe]

@microsoft-github-policy-service agree

[Copilot]

🟡 Changes recommended

The tutorial contains multiple incorrect or non-compiling examples that should be fixed before approval.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds a getting-started tutorial for cppgraphqlgen.

Changes:

• Documents schema generation and generated C++ types.
• Shows resolver, object, and service implementations.
• Demonstrates query execution and JSON serialization.

File summaries

File	Summary
doc/getting_started.md	Adds the complete getting-started tutorial and requires corrections to several examples.

Review details

Suppressed comments (13)

doc/getting_started.md:167

• This second namespace mod_graphql::mock ... declaration has the same invalid C++ syntax and is also left unclosed, so the Thing example cannot be copied into a compilable source file.

namespace mod_graphql::mock ...

doc/getting_started.md:198

• The command above uses prefix as the filename prefix, so the generated schema header is prefixSchema.h; gsm is only the namespace. gsmSchema.h does not exist, so this include makes the example fail to compile.

#include "gsmSchema.h"

doc/getting_started.md:228

• This snippet uses std::cerr and std::endl, but the headers shown above do not include <iostream>; GraphQLService.h does not provide that header transitively. A translation unit copied from these steps can therefore fail to compile.

  std::cerr << e.what() << std::endl;

doc/getting_started.md:6

• Use the standard acronym spelling JSON in this user-facing description.

The final goal is to write a basic system, which given an input *query string* will return an *output in Json format*.

doc/getting_started.md:3

• The document uses # for both the title and section headings, whereas the existing documentation uses one H1 title followed by ## sections (for example, doc/parsing.md:1-3). This breaks the heading hierarchy and generated table-of-contents structure; make About, The Schema, and Implementation level-two headings.

# About

doc/getting_started.md:103

• This description is misleading in two important ways: the inline type has an extra >, and [String!]! requires a non-null list and non-null elements but still permits an empty vector. Readers should not infer that the resolver must return at least one string.

If we take as an example `getNames` we can see how the return type is indicated in the function signature, it returns a `service::AwaitableScalar<std::vector<std::string>>`, meaning that our code will have to return a `std::vector<std::string>>`; which makes sense, considering how schema returns an array of string that is *mandatory*, as in, the query *must return the field with something*.

doc/getting_started.md:124

• namespace mod_graphql::mock ... is not valid C++ syntax, and neither code block shows the closing namespace brace. Since these are presented as implementation snippets, readers cannot compile them as written.

namespace mod_graphql::mock ...

doc/getting_started.md:152

• Thing is defined only in the later code block, after this make_shared<Thing> is compiled. The type must be declared and complete before this function definition, or the implementation must be moved below the Thing definition.

  auto thing_ptr = std::make_shared<Thing>(0, "Sample Description!");

doc/getting_started.md:153

• object::Thing is constructed here, but QueryObject.h only provides the generated type's forward declaration. The translation unit also needs the generated <prefix>ThingObject.h definition before calling std::make_shared for this type.

  stuff.push_back(std::make_shared<::graphql::gsm::object::Thing>(thing_ptr));

doc/getting_started.md:167

• This repeats the invalid namespace mod_graphql::mock ... syntax and omits the closing brace, so the Thing implementation is not compilable as shown. Use a real namespace body and close it around the class definition.

namespace mod_graphql::mock ...

doc/getting_started.md:200

• The generated schema filename follows the prefix argument (<prefix>Schema.h), while this example includes gsmSchema.h; it also uses std::cerr and std::endl below without including <iostream>. As written, the service setup example is not self-contained or compilable.

#include "gsmSchema.h"
#include <graphqlservice/GraphQLService.h>
#include <graphqlservice/JSONResponse.h>

doc/getting_started.md:226

• parseString returns an AST with a null root when parsing fails, and Request::resolve dereferences params.query.root; this example must check query_ast.root before resolving it. The existing samples perform this guard before calling resolve.

  ::graphql::peg::ast query_ast = ::graphql::peg::parseString(query_input);
  final_output =
      ::graphql::response::toJSON(service->resolve({query_ast, ""}).get());

doc/getting_started.md:111

• The implementation is not required to return the literal <std::vector...> expression shown here; it should return a std::vector<std::shared_ptr<Thing>>, which the generated AwaitableObject wraps implicitly. The current wording also has the grammar error must to return and can render the type as malformed Markdown.

The return value is `service::AwaitableObject<std::vector<std::shared_ptr<Thing>>>`, this means that we *must* to return a `<std::vector<std::shared_ptr<Thing>>`; once again it's a vector since the GraphQL schema declared a list.

• Files reviewed: 1/1 changed files
• Comments generated: 6
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.