Documentation improvements and labeled examples (#216)

Improve documentation for calculations
Add ability to "label" examples by passing a tuple instead of just a string.
Fix some minor typos

documentation/topics/calculations.md

@@ -13,9 +13,12 @@ Example:
 
 ```elixir
 defmodule Concat do
-  # An example concatenation calculation, that accepts the delimeter as an argument, and the fields to concatenate as options
+  # An example concatenation calculation, that accepts the delimeter as an argument,
+  #and the fields to concatenate as options
   use Ash.Calculation, type: :string
 
+  # Optional callback that verifies the passed in options (and optionally transforms them)
+  @impl true
   def init(opts) do
     if opts[:keys] && is_list(opts[:keys]) && Enum.all?(opts[:keys], &is_atom/1) do
       {:ok, opts}
@@ -24,6 +27,7 @@ defmodule Concat do
     end
   end
 
+  @impl true
   def calculate(records, opts, %{separator: separator}) do
     Enum.map(records, fn record ->
       Enum.map_join(opts[:keys], separator, fn key ->
@@ -44,7 +48,7 @@ calculations do
 end
 ```
 
-See the documentation for the calculations section in `Ash.Resource.Dsl` for more information.
+See the documentation for the calculations section in `Ash.Resource.Dsl` and the `Ash.Calculation` docs for more information.
 
 The calculations declared on a resource allow for declaring a set of named calculations that can be used by extensions.
 They can also be loaded in the query using `Ash.Query.load/2`, or after the fact using `c:Ash.Api.load/3`. Calculations declared on the resource will be keys in the resource's struct.

lib/ash/dsl/extension.ex

@@ -2,7 +2,7 @@ defmodule Ash.Dsl.Extension do
   @moduledoc """
   An extension to the Ash DSL.
 
-  This allows configuring custom DSL components, whos configurations
+  This allows configuring custom DSL components, whose configurations
   can then be read back. This guide is still a work in progress, but should
   serve as a decent example of what is possible. Open issues on Github if you
   have any issues/something is unclear.
@@ -213,14 +213,7 @@ defmodule Ash.Dsl.Extension do
           ""
 
         examples ->
-          "Examples:\n" <>
-            Enum.map_join(examples, fn example ->
-              """
-              ```
-              #{example}
-              ```
-              """
-            end)
+          "Examples:\n" <> Enum.map_join(examples, &doc_example/1)
       end
 
     entities =
@@ -281,14 +274,7 @@ defmodule Ash.Dsl.Extension do
           ""
 
         examples ->
-          "Examples:\n" <>
-            Enum.map_join(examples, fn example ->
-              """
-              ```
-              #{example}
-              ```
-              """
-            end)
+          "Examples:\n" <> Enum.map_join(examples, &doc_example/1)
       end
 
     entities =
@@ -355,6 +341,23 @@ defmodule Ash.Dsl.Extension do
     end
   end
 
+  defp doc_example({description, example}) when is_binary(description) and is_binary(example) do
+    """
+    #{description}
+    ```
+    #{example}
+    ```
+    """
+  end
+
+  defp doc_example(example) when is_binary(example) do
+    """
+    ```
+    #{example}
+    ```
+    """
+  end
+
   @doc false
   defmacro __using__(opts) do
     quote bind_quoted: [

lib/ash/resource/calculation/calculation.ex

@@ -15,7 +15,7 @@ defmodule Ash.Resource.Calculation do
     calculation: [
       type: {:custom, __MODULE__, :calculation, []},
       required: true,
-      doc: "The module or {module, opts} to use for the calculation"
+      doc: "The module or `{module, opts}` to use for the calculation"
     ],
     description: [
       type: :string,

lib/ash/resource/dsl.ex

@@ -799,7 +799,10 @@ defmodule Ash.Resource.Dsl do
     """,
     examples: [
       "calculate :full_name, :string, MyApp.MyResource.FullName",
-      "calculate :full_name, :string, {MyApp.FullName, keys: [:first_name, :last_name]}",
+      {
+        "`Ash.Calculation` implementation example:",
+        "calculate :full_name, :string, {MyApp.FullName, keys: [:first_name, :last_name]}"
+      },
       "calculate :full_name, :string, full_name([:first_name, :last_name])"
     ],
     target: Ash.Resource.Calculation,