Merge pull request #243 from wravery/doc-updates

Update docs for next release

Author: wravery

doc/awaitable.md

@@ -8,14 +8,14 @@ specifically a type-erased `graphql::service::await_async` class in
 [GraphQLService.h](../include/graphqlservice/GraphQLService.h):
 ```cpp
 // Type-erased awaitable.
-class await_async final
+class [[nodiscard]] await_async final
 {
 private:
-	struct Concept
+	struct [[nodiscard]] Concept
 	{
 		virtual ~Concept() = default;
 
-		virtual bool await_ready() const = 0;
+		[[nodiscard]] virtual bool await_ready() const = 0;
 		virtual void await_suspend(coro::coroutine_handle<> h) const = 0;
 		virtual void await_resume() const = 0;
 	};
@@ -71,22 +71,22 @@ Many APIs which used to return some sort of `std::future` now return an alias fo
 `graphql::internal::Awaitable<...>`. This template is defined in [Awaitable.h](../include/graphqlservice/internal/Awaitable.h):
 ```cpp
 template <typename T>
-class Awaitable
+class [[nodiscard]] Awaitable
 {
 public:
 	Awaitable(std::future<T> value)
 		: _value { std::move(value) }
 	{
 	}
 
-	T get()
+	[[nodiscard]] T get()
 	{
 		return _value.get();
 	}
 
 	struct promise_type
 	{
-		Awaitable get_return_object() noexcept
+		[[nodiscard]] Awaitable get_return_object() noexcept
 		{
 			return { _promise.get_future() };
 		}
@@ -105,7 +105,7 @@ public:
 
 	};
 
-	constexpr bool await_ready() const noexcept
+	[[nodiscard]] constexpr bool await_ready() const noexcept
 	{
 		return true;
 	}
@@ -115,7 +115,7 @@ public:
 		h.resume();
 	}
 
-	T await_resume()
+	[[nodiscard]] T await_resume()
 	{
 		return _value.get();
 	}

doc/fieldparams.md

@@ -21,7 +21,7 @@ The `graphql::service::FieldParams` struct is declared in [GraphQLService.h](../
 ```cpp
 // Pass a common bundle of parameters to all of the generated Object::getField accessors in a
 // SelectionSet
-struct SelectionSetParams
+struct [[nodiscard]] SelectionSetParams
 {
 	// Context for this selection set.
 	const ResolverContext resolverContext;
@@ -46,7 +46,7 @@ struct SelectionSetParams
 };
 
 // Pass a common bundle of parameters to all of the generated Object::getField accessors.
-struct FieldParams : SelectionSetParams
+struct [[nodiscard]] FieldParams : SelectionSetParams
 {
 	GRAPHQLSERVICE_EXPORT explicit FieldParams(
 		SelectionSetParams&& selectionSetParams, Directives directives);
@@ -64,8 +64,7 @@ The `SelectionSetParams::resolverContext` enum member informs the `getField`
 accessors about what type of operation is being resolved:
 ```cpp
 // Resolvers may be called in multiple different Operation contexts.
-enum class ResolverContext
-{
+enum class [[nodiscard]] ResolverContext {
 	// Resolving a Query operation.
 	Query,
 
@@ -95,8 +94,9 @@ The `SelectionSetParams::state` member is a reference to the
 // any per-request state that you want to maintain throughout the request (e.g. optimizing or
 // batching backend requests), you can inherit from RequestState and pass it to Request::resolve to
 // correlate the asynchronous/recursive callbacks and accumulate state in it.
-struct RequestState : std::enable_shared_from_this<RequestState>
+struct [[nodiscard]] RequestState : std::enable_shared_from_this<RequestState>
 {
+	virtual ~RequestState() = default;
 };
 ```
 

doc/json.md

@@ -46,7 +46,7 @@ to some other output mechanism, without building a single string buffer for the
 document in memory. For example, you might use this to write directly to a buffered IPC pipe
 or network connection:
 ```cpp
-class Writer final
+class [[nodiscard]] Writer final
 {
 private:
 	struct Concept

doc/responses.md

@@ -10,17 +10,17 @@ represented in GraphQL, as of the
 [October 2021 spec](https://spec.graphql.org/October2021/#sec-Serialization-Format):
 
 ```c++
-enum class Type : uint8_t
-{
-	Map,		// JSON Object
-	List,		// JSON Array
-	String,		// JSON String
-	Null,		// JSON null
-	Boolean,	// JSON true or false
-	Int,		// JSON Number
-	Float,		// JSON Number
-	EnumValue,	// JSON String
-	Scalar,		// JSON any type
+enum class [[nodiscard]] Type : std::uint8_t {
+	Map,	   // JSON Object
+	List,	   // JSON Array
+	String,	   // JSON String
+	Null,	   // JSON null
+	Boolean,   // JSON true or false
+	Int,	   // JSON Number
+	Float,	   // JSON Number
+	EnumValue, // JSON String
+	ID,		   // JSON String
+	Scalar,	   // JSON any type
 };
 ```
 

doc/subscriptions.md

@@ -13,13 +13,13 @@ the subscriptions to those listeners.
 Subscriptions are created by calling the `Request::subscribe` method in
 [GraphQLService.h](../include/graphqlservice/GraphQLService.h):
 ```cpp
-GRAPHQLSERVICE_EXPORT AwaitableSubscribe subscribe(RequestSubscribeParams params);
+GRAPHQLSERVICE_EXPORT [[nodiscard]] AwaitableSubscribe subscribe(RequestSubscribeParams params);
 ```
 
 You need to fill in a `RequestSubscribeParams` struct with the subscription event
 callback, the [parsed](./parsing.md) `query` and any other relevant operation parameters:
 ```cpp
-struct RequestSubscribeParams
+struct [[nodiscard]] RequestSubscribeParams
 {
 	// Callback which receives the event data.
 	SubscriptionCallback callback;
@@ -34,6 +34,9 @@ struct RequestSubscribeParams
 
 	// Optional sub-class of RequestState which will be passed to each resolver and field accessor.
 	std::shared_ptr<RequestState> state;
+
+	// Optional override for the default Subscription operation object.
+	std::shared_ptr<const Object> subscriptionObject {};
 };
 ```
 
@@ -61,19 +64,22 @@ The `internal::Awaitable<T>` template is described in [awaitable.md](./awaitable
 Subscriptions are removed by calling the `Request::unsubscribe` method in
 [GraphQLService.h](../include/graphqlservice/GraphQLService.h):
 ```cpp
-GRAPHQLSERVICE_EXPORT AwaitableUnsubscribe unsubscribe(RequestUnsubscribeParams params);
+GRAPHQLSERVICE_EXPORT [[nodiscard]] AwaitableUnsubscribe unsubscribe(RequestUnsubscribeParams params);
 ```
 
 You need to fill in a `RequestUnsubscribeParams` struct with the `SubscriptionKey`
 returned by `Request::subscribe` in `AwaitableSubscribe`:
 ```cpp
-struct RequestUnsubscribeParams
+struct [[nodiscard]] RequestUnsubscribeParams
 {
 	// Key returned by a previous call to subscribe.
 	SubscriptionKey key;
 
 	// Optional async execution awaitable.
 	await_async launch;
+
+	// Optional override for the default Subscription operation object.
+	std::shared_ptr<const Object> subscriptionObject {};
 };
 ```
 
@@ -83,12 +89,12 @@ By default, the resolvers will run on the same thread synchronously.
 ## `ResolverContext::NotifySubscribe` and `ResolverContext::NotifyUnsubscribe`
 
 If you provide a default instance of the `Subscription` object to the `Request`/
-`Operations` constructor, you will get additional callbacks with the
-`ResolverContext::NotifySubscribe` and `ResolverContext::NotifyUnsubscribe` values
-for the `FieldParams::resolverContext` member. These are passed by the
-`subscribe` and `unsubscribe` calls to the default subscription object, and
-they provide an opportunity to acquire or release resources that are required
-to implement the subscription.
+`Operations` constructor, or in the `RequestSubscribeParams`/`RequestUnsubscribeParams`
+struct, you will get additional callbacks with the `ResolverContext::NotifySubscribe`
+and `ResolverContext::NotifyUnsubscribe` values for the `FieldParams::resolverContext`
+member. These are passed by the `subscribe` and `unsubscribe` calls to the default
+subscription object, and they provide an opportunity to acquire or release resources
+that are required to implement the subscription.
 
 You can provide separate implementations of the `Subscription` object as the
 default in the `Operations` constructor and as the payload of a specific
@@ -111,7 +117,7 @@ The `Request::deliver` method determines which subscriptions should receive
 an event based on several factors, which makes the `RequestDeliverParams` struct
 more complicated:
 ```cpp
-struct RequestDeliverParams
+struct [[nodiscard]] RequestDeliverParams
 {
 	// Deliver to subscriptions on this field.
 	std::string_view field;
@@ -149,7 +155,7 @@ using SubscriptionArguments = std::map<std::string_view, response::Value>;
 using SubscriptionArgumentFilterCallback = std::function<bool(response::MapType::const_reference)>;
 using SubscriptionDirectiveFilterCallback = std::function<bool(Directives::const_reference)>;
 
-struct SubscriptionFilter
+struct [[nodiscard]] SubscriptionFilter
 {
 	// Optional field argument filter, which can either be a set of required arguments, or a
 	// callback which returns true if the arguments match custom criteria.
@@ -180,6 +186,6 @@ that, there's a public `Request::findOperationDefinition` method which returns
 the operation type as a `std::string_view` along with a pointer to the AST node
 for the selected operation in the parsed query:
 ```cpp
-GRAPHQLSERVICE_EXPORT std::pair<std::string_view, const peg::ast_node*> findOperationDefinition(
-	peg::ast& query, std::string_view operationName) const;
+GRAPHQLSERVICE_EXPORT [[nodiscard]] std::pair<std::string_view, const peg::ast_node*>
+findOperationDefinition(peg::ast& query, std::string_view operationName) const;
 ```

include/graphqlservice/internal/Awaitable.h

@@ -40,7 +40,7 @@ class [[nodiscard]] Awaitable<void>
 
 	struct promise_type
 	{
-		Awaitable get_return_object() noexcept
+		[[nodiscard]] Awaitable get_return_object() noexcept
 		{
 			return { _promise.get_future() };
 		}
@@ -69,7 +69,7 @@ class [[nodiscard]] Awaitable<void>
 		std::promise<void> _promise;
 	};
 
-	constexpr bool await_ready() const noexcept
+	[[nodiscard]] constexpr bool await_ready() const noexcept
 	{
 		return true;
 	}
@@ -97,14 +97,14 @@ class [[nodiscard]] Awaitable
 	{
 	}
 
-	T get()
+	[[nodiscard]] T get()
 	{
 		return _value.get();
 	}
 
 	struct promise_type
 	{
-		Awaitable get_return_object() noexcept
+		[[nodiscard]] Awaitable get_return_object() noexcept
 		{
 			return { _promise.get_future() };
 		}
@@ -138,7 +138,7 @@ class [[nodiscard]] Awaitable
 		std::promise<T> _promise;
 	};
 
-	constexpr bool await_ready() const noexcept
+	[[nodiscard]] constexpr bool await_ready() const noexcept
 	{
 		return true;
 	}
@@ -148,7 +148,7 @@ class [[nodiscard]] Awaitable
 		h.resume();
 	}
 
-	T await_resume()
+	[[nodiscard]] T await_resume()
 	{
 		return _value.get();
 	}