chore(docs): Update custom_input with and transform examples to return value only (#1938)

Author: chazwatkins

documentation/dsls/DSL-Ash.Domain.md

@@ -147,7 +147,7 @@ custom_input name, type
 ```
 
 
-Define or customize an input to the action. 
+Define or customize an input to the action.
 
 See the [code interface guide](/documentation/topics/resources/code-interfaces.md) for more.
 
@@ -159,7 +159,7 @@ See the [code interface guide](/documentation/topics/resources/code-interfaces.m
 ### Examples
 ```
 custom_input :artist, :struct do
-  transform to: :artist_id, with: &{:ok, &1.id}
+  transform to: :artist_id, using: &(&1.id)
 
   constraints instance_of: Artist
 end
@@ -195,17 +195,17 @@ A transformation to be applied to the custom input.
 
 ### Examples
 ```
-transform do 
+transform do
   to :artist_id
-  with &{:ok, &1.id}
+  using &(&1.id)
 end
 
 ```
 
 ```
-transform do 
+transform do
   to :points
-  with &try_parse_integer/1
+  using &try_parse_integer/1
 end
 
 ```
@@ -218,7 +218,7 @@ end
 | Name | Type | Default | Docs |
 |------|------|---------|------|
 | [`to`](#resources-resource-define-custom_input-transform-to){: #resources-resource-define-custom_input-transform-to } | `atom` |  | A key to rewrite the argument to. If the custom input is also a required positional argument, then the `to` is automatically added to the `exclude_inputs` list. |
-| [`using`](#resources-resource-define-custom_input-transform-using){: #resources-resource-define-custom_input-transform-using } | `(any -> any)` |  | A function to use to transform the value. Must return `{:ok, value}` or `{:error, error}` |
+| [`using`](#resources-resource-define-custom_input-transform-using){: #resources-resource-define-custom_input-transform-using } | `(any -> any)` |  | A function to use to transform the value. Must return `value` or `nil` |
 
 
 
@@ -287,7 +287,7 @@ custom_input name, type
 ```
 
 
-Define or customize an input to the action. 
+Define or customize an input to the action.
 
 See the [code interface guide](/documentation/topics/resources/code-interfaces.md) for more.
 
@@ -299,7 +299,7 @@ See the [code interface guide](/documentation/topics/resources/code-interfaces.m
 ### Examples
 ```
 custom_input :artist, :struct do
-  transform to: :artist_id, with: &{:ok, &1.id}
+  transform to: :artist_id, using: &(&1.id)
 
   constraints instance_of: Artist
 end
@@ -335,17 +335,17 @@ A transformation to be applied to the custom input.
 
 ### Examples
 ```
-transform do 
+transform do
   to :artist_id
-  with &{:ok, &1.id}
+  using &(&1.id)
 end
 
 ```
 
 ```
-transform do 
+transform do
   to :points
-  with &try_parse_integer/1
+  using &try_parse_integer/1
 end
 
 ```
@@ -358,7 +358,7 @@ end
 | Name | Type | Default | Docs |
 |------|------|---------|------|
 | [`to`](#resources-resource-define_calculation-custom_input-transform-to){: #resources-resource-define_calculation-custom_input-transform-to } | `atom` |  | A key to rewrite the argument to. If the custom input is also a required positional argument, then the `to` is automatically added to the `exclude_inputs` list. |
-| [`using`](#resources-resource-define_calculation-custom_input-transform-using){: #resources-resource-define_calculation-custom_input-transform-using } | `(any -> any)` |  | A function to use to transform the value. Must return `{:ok, value}` or `{:error, error}` |
+| [`using`](#resources-resource-define_calculation-custom_input-transform-using){: #resources-resource-define_calculation-custom_input-transform-using } | `(any -> any)` |  | A function to use to transform the value. Must return `value` or `nil` |
 
 
 

documentation/dsls/DSL-Ash.Resource.md

@@ -2061,7 +2061,7 @@ custom_input name, type
 ```
 
 
-Define or customize an input to the action. 
+Define or customize an input to the action.
 
 See the [code interface guide](/documentation/topics/resources/code-interfaces.md) for more.
 
@@ -2073,7 +2073,7 @@ See the [code interface guide](/documentation/topics/resources/code-interfaces.m
 ### Examples
 ```
 custom_input :artist, :struct do
-  transform to: :artist_id, with: &{:ok, &1.id}
+  transform to: :artist_id, using: &(&1.id)
 
   constraints instance_of: Artist
 end
@@ -2109,17 +2109,17 @@ A transformation to be applied to the custom input.
 
 ### Examples
 ```
-transform do 
+transform do
   to :artist_id
-  with &{:ok, &1.id}
+  using &(&1.id)
 end
 
 ```
 
 ```
-transform do 
+transform do
   to :points
-  with &try_parse_integer/1
+  using &try_parse_integer/1
 end
 
 ```
@@ -2132,7 +2132,7 @@ end
 | Name | Type | Default | Docs |
 |------|------|---------|------|
 | [`to`](#code_interface-define-custom_input-transform-to){: #code_interface-define-custom_input-transform-to } | `atom` |  | A key to rewrite the argument to. If the custom input is also a required positional argument, then the `to` is automatically added to the `exclude_inputs` list. |
-| [`using`](#code_interface-define-custom_input-transform-using){: #code_interface-define-custom_input-transform-using } | `(any -> any)` |  | A function to use to transform the value. Must return `{:ok, value}` or `{:error, error}` |
+| [`using`](#code_interface-define-custom_input-transform-using){: #code_interface-define-custom_input-transform-using } | `(any -> any)` |  | A function to use to transform the value. Must return `value` or `nil` |
 
 
 
@@ -2201,7 +2201,7 @@ custom_input name, type
 ```
 
 
-Define or customize an input to the action. 
+Define or customize an input to the action.
 
 See the [code interface guide](/documentation/topics/resources/code-interfaces.md) for more.
 
@@ -2213,7 +2213,7 @@ See the [code interface guide](/documentation/topics/resources/code-interfaces.m
 ### Examples
 ```
 custom_input :artist, :struct do
-  transform to: :artist_id, with: &{:ok, &1.id}
+  transform to: :artist_id, using: &(&1.id)
 
   constraints instance_of: Artist
 end
@@ -2249,17 +2249,17 @@ A transformation to be applied to the custom input.
 
 ### Examples
 ```
-transform do 
+transform do
   to :artist_id
-  with &{:ok, &1.id}
+  using &(&1.id)
 end
 
 ```
 
 ```
-transform do 
+transform do
   to :points
-  with &try_parse_integer/1
+  using &try_parse_integer/1
 end
 
 ```
@@ -2272,7 +2272,7 @@ end
 | Name | Type | Default | Docs |
 |------|------|---------|------|
 | [`to`](#code_interface-define_calculation-custom_input-transform-to){: #code_interface-define_calculation-custom_input-transform-to } | `atom` |  | A key to rewrite the argument to. If the custom input is also a required positional argument, then the `to` is automatically added to the `exclude_inputs` list. |
-| [`using`](#code_interface-define_calculation-custom_input-transform-using){: #code_interface-define_calculation-custom_input-transform-using } | `(any -> any)` |  | A function to use to transform the value. Must return `{:ok, value}` or `{:error, error}` |
+| [`using`](#code_interface-define_calculation-custom_input-transform-using){: #code_interface-define_calculation-custom_input-transform-using } | `(any -> any)` |  | A function to use to transform the value. Must return `value` or `nil` |
 
 
 

documentation/topics/resources/code-interfaces.md

@@ -163,7 +163,7 @@ MyApp.Blog.my_posts(stream?: true, actor: me)
 ### Customizing the generated function
 
 Often we want to have a slightly different interface when calling actions with functions,
-or we want to maintain backwards compatibility for callers of our code interface while 
+or we want to maintain backwards compatibility for callers of our code interface while
 changing the underlying action implementation.
 
 You can define `custom_input`s on your code interfaces to massage arguments from the function
@@ -194,11 +194,11 @@ define :follow_artist do
       to :artist_id
 
       # Extracting the value using this function
-      using fn 
-        %Ash.Union{type: :artist, value: value} -> 
-          {:ok, value.id}
+      using fn
+        %Ash.Union{type: :artist, value: value} ->
+          value.id
         %Ash.Union{type: :artist_id, value: value} ->
-          {:ok, value}
+          value
       end
     end
   end
@@ -217,8 +217,8 @@ defmodule MyApp.Types.ArtistOrId do
     ]
   ]
 
-  def to_artist_id(%Ash.Union{type: :artist, value: artist}), do: {:ok, artist.id}
-  def to_artist_id(%Ash.Union{type: :artist_id, value: artist_id}), do: {:ok, artist_id}
+  def to_artist_id(%Ash.Union{type: :artist, value: artist}), do: artist.id
+  def to_artist_id(%Ash.Union{type: :artist_id, value: artist_id}), do: artist_id
 end
 ```
 

lib/ash/resource/dsl.ex

@@ -881,15 +881,15 @@ defmodule Ash.Resource.Dsl do
     """,
     examples: [
       """
-      transform do 
+      transform do
         to :artist_id
-        with &{:ok, &1.id}
+        using &(&1.id)
       end
       """,
       """
-      transform do 
+      transform do
         to :points
-        with &try_parse_integer/1
+        using &try_parse_integer/1
       end
       """
     ],
@@ -902,23 +902,22 @@ defmodule Ash.Resource.Dsl do
       ],
       using: [
         type: {:fun, 1},
-        doc:
-          "A function to use to transform the value. Must return `{:ok, value}` or `{:error, error}`"
+        doc: "A function to use to transform the value. Must return `value` or `nil`"
       ]
     ]
   }
 
   @custom_input %Spark.Dsl.Entity{
     name: :custom_input,
     describe: """
-    Define or customize an input to the action. 
+    Define or customize an input to the action.
 
     See the [code interface guide](/documentation/topics/resources/code-interfaces.md) for more.
     """,
     examples: [
       """
       custom_input :artist, :struct do
-        transform to: :artist_id, with: &{:ok, &1.id}
+        transform to: :artist_id, using: &(&1.id)
 
         constraints instance_of: Artist
       end