docs: Spelling fixes, add :upsert_identity example (#327)

* Minor spelling fixes, :upsert_identity example

* Grammatical tweaks in API docs

* Adjust phrasing, consistent formatting

lib/ash/api/api.ex

@@ -88,7 +88,7 @@ defmodule Ash.Api do
       type: :boolean,
       default: true,
       doc:
-        "For Ash errors, wether or not each error has a stacktrace. See the error_handling guide for more."
+        "For Ash errors, whether or not each error has a stacktrace. See the error_handling guide for more."
     ],
     tenant: [
       type: :any,
@@ -271,7 +271,7 @@ defmodule Ash.Api do
       ```
 
       If you tried to load that `:full_name` calculation after receiving the data, the `last_name` would not be selected and as such would not be
-      usable in the calculation, regardless of wether or not the calculation includes that field in its select list.
+      usable in the calculation, regardless of whether or not the calculation includes that field in its select list.
       """
     ]
   ]
@@ -286,7 +286,7 @@ defmodule Ash.Api do
                         upsert_identity: [
                           type: :atom,
                           doc:
-                            "The identity to use when detecting conflicts for upsert?. By default, the primary key is used. Has no effect if `upsert?: true` is not provided"
+                            "The identity to use when detecting conflicts for `upsert?`, e.g. `upsert_identity: :full_name`. By default, the primary key is used. Has no effect if `upsert?: true` is not provided"
                         ]
                       ]
                       |> merge_schemas(@global_opts, "Global Options")
@@ -364,10 +364,10 @@ defmodule Ash.Api do
               Ash.Resource.record() | {Ash.Resource.record(), Ash.Query.t()} | no_return
 
   @doc """
-  Run a query on a resource, but fail on more than one result
+  Run a query on a resource, but fail on more than one result.
 
   This is useful if you have a query that doesn't include a primary key
-  but you know that it will only ever return a single result
+  but you know that it will only ever return a single result.
   """
   @callback read_one(Ash.Query.t() | Ash.Resource.t(), params :: Keyword.t()) ::
               {:ok, Ash.Resource.record()}
@@ -384,7 +384,7 @@ defmodule Ash.Api do
   @doc """
   Run a query on a resource.
 
-  For more information, on building a query, see `Ash.Query`.
+  For more information on building a query, see `Ash.Query`.
 
   #{Ash.OptionsHelpers.docs(@read_opts_schema)}
 
@@ -572,7 +572,7 @@ defmodule Ash.Api do
   Gets the resources of an Api module. DO NOT USE AT COMPILE TIME.
 
   If you need the resource list at compile time, you will need to introduce a compile time
-  dependency on all of the resources, and therefore should use the registry directly. `Registry |> Ash.Registry.entries()`
+  dependency on all of the resources, and therefore should use the registry directly. `Registry |> Ash.Registry.entries()`.
   """
   @spec resources(Ash.Api.t()) :: list(Ash.Resource.t())
   def resources(api) do

lib/ash/api/dsl.ex

@@ -34,7 +34,7 @@ defmodule Ash.Api.Dsl do
       allow: [
         type: :mfa,
         doc: """
-        Support a dynamic resource list by providing a callback that checks wether or not the resource should be allowed.
+        Support a dynamic resource list by providing a callback that checks whether or not the resource should be allowed.
         """
       ],
       allow_unregistered?: [

lib/ash/engine/engine.ex

@@ -16,7 +16,7 @@ defmodule Ash.Engine do
   As the complexity of a system grows, it becomes very difficult to write code that
   is both imperative and performant. This is especially true of a framework that is
   designed to be configurable. What exactly is done, as well as the order it is done in,
-  and wether or not is can be parallelized, varies wildly based on factors like how
+  and whether or not is can be parallelized, varies wildly based on factors like how
   the resources are configured and what capabilities the data layer has. By implementing
   a generic "parallel engine", we can let the engine solve that problem. We simply
   have to express the various operations that must happen, and what other pieces of data

lib/ash/engine/request.ex

@@ -46,7 +46,7 @@ defmodule Ash.Engine.Request do
 
   defmodule UnresolvedField do
     @moduledoc """
-    Represents an unresolved field to be resolved by the engine
+    Represents an unresolved field to be resolved by the engine.
     """
     defstruct [:resolver, deps: [], data?: false]
 
@@ -86,7 +86,7 @@ defmodule Ash.Engine.Request do
   being processed, like `[:data]`, and the last element is the
   key of that request that is required. Make sure to pass a
   list of lists of atoms. The second argument is a map, which
-  contains all the values you requested, at the same path
+  contains all of the values you requested, at the same path
   that they were requested.
 
   For example:
@@ -136,7 +136,7 @@ defmodule Ash.Engine.Request do
     * name - A human readable name for the request, used when logging/in errors
     * strict_check_only? - If true, authorization will not be allowed to proceed to a runtime check (so it cannot run db queries unless authorization is assured)
     * actor - The actor performing the action, used for authorization
-    * authorize? - Wether or not to perform authorization (defaults to true)
+    * authorize? - Whether or not to perform authorization (defaults to true)
     * verbose? - print informational logs (warning, this will be a whole lot of logs)
     * write_to_data? - If set to false, this value is not returned from the initial call to the engine
   """

lib/ash/resource/actions/shared_options.ex

@@ -19,7 +19,7 @@ defmodule Ash.Resource.Actions.SharedOptions do
     transaction?: [
       type: :boolean,
       doc: """
-      Wether or not the action should be run in transactions. Reads default to false, while create/update/destroy actions default to `true`.
+      Whether or not the action should be run in transactions. Reads default to false, while create/update/destroy actions default to `true`.
 
       Has no effect if the data layer does not support transactions, or if that data layer is already in a transaction.
       """