From 7721dc1c61b3ff8510c8f32a58e254a93d126e1b Mon Sep 17 00:00:00 2001
From: James Harton <james@harton.dev>
Date: Thu, 4 Apr 2024 15:56:42 +1300
Subject: [PATCH] fix: multi-line DSL doc options in `Ash.Reactor`. (#974)

Closes #973.
---
 documentation/dsls/DSL:-Ash.Reactor.md | 86 +++++++++++++++++++-------
 lib/ash/reactor/dsl/action.ex          | 33 +++++-----
 lib/ash/reactor/dsl/actor.ex           | 12 +---
 lib/ash/reactor/dsl/create.ex          |  6 +-
 lib/ash/reactor/dsl/destroy.ex         |  6 +-
 lib/ash/reactor/dsl/inputs.ex          |  6 +-
 lib/ash/reactor/dsl/tenant.ex          | 12 +---
 lib/ash/reactor/dsl/transaction.ex     |  7 +--
 lib/ash/reactor/dsl/update.ex          |  6 +-
 9 files changed, 106 insertions(+), 68 deletions(-)

diff --git a/documentation/dsls/DSL:-Ash.Reactor.md b/documentation/dsls/DSL:-Ash.Reactor.md
index 6a2abe59..386f2d3b 100644
--- a/documentation/dsls/DSL:-Ash.Reactor.md
+++ b/documentation/dsls/DSL:-Ash.Reactor.md
@@ -36,6 +36,16 @@ action name, resource, action \\ nil
 
 Declares a step that will call a generic action on a resource.
 
+> #### Undo behaviour {: .tip}
+>
+> This step has three different modes of undo.
+>
+> * `never` - The result of the action is never undone.  This is the default.
+> * `always` - The `undo_action` will always be called.
+> * `outside_transaction` - The `undo_action` will not be called when running inside a `transaction` block, but will be otherwise.
+
+
+
 ### Nested DSLs
  * [actor](#reactor-action-actor)
  * [inputs](#reactor-action-inputs)
@@ -49,7 +59,7 @@ Declares a step that will call a generic action on a resource.
 
 | Name | Type | Default | Docs |
 |------|------|---------|------|
-| [`name`](#reactor-action-name){: #reactor-action-name .spark-required} | `atom` |  | A unique name for the step. This is used when choosing the return value of the Reactor and for arguments into other steps. |
+| [`name`](#reactor-action-name){: #reactor-action-name .spark-required} | `atom` |  | A unique name for the step. |
 | [`resource`](#reactor-action-resource){: #reactor-action-resource .spark-required} | `module` |  | The resource to call the action on. |
 | [`action`](#reactor-action-action){: #reactor-action-action } | `atom` |  | The name of the action to call on the resource. |
 ### Options
@@ -61,7 +71,7 @@ Declares a step that will call a generic action on a resource.
 | [`authorize?`](#reactor-action-authorize?){: #reactor-action-authorize? } | `boolean \| nil` |  | Explicitly enable or disable authorization for the action. |
 | [`description`](#reactor-action-description){: #reactor-action-description } | `String.t` |  | A description for the step |
 | [`undo_action`](#reactor-action-undo_action){: #reactor-action-undo_action } | `atom` |  | The name of the action to call on the resource when the step is to be undone. |
-| [`undo`](#reactor-action-undo){: #reactor-action-undo } | `:always \| :never \| :outside_transaction` | `:never` | What to do when the reactor is undoing it's work? * `always` - The undo action will always be run. * `never` - The action will never be undone. * `outside_transaction` - The action will only be undone if not running inside a transaction. |
+| [`undo`](#reactor-action-undo){: #reactor-action-undo } | `:always \| :never \| :outside_transaction` | `:never` | How to handle undoing this action |
 
 
 ## reactor.action.actor
@@ -80,7 +90,7 @@ Specifies the action actor
 
 | Name | Type | Default | Docs |
 |------|------|---------|------|
-| [`source`](#reactor-action-actor-source){: #reactor-action-actor-source .spark-required} | `Reactor.Template.Input \| Reactor.Template.Result \| Reactor.Template.Value` |  | What to use as the source of the actor. See `Reactor.Dsl.Argument` for more information. |
+| [`source`](#reactor-action-actor-source){: #reactor-action-actor-source .spark-required} | `Reactor.Template.Input \| Reactor.Template.Result \| Reactor.Template.Value` |  | What to use as the source of the actor. |
 ### Options
 
 | Name | Type | Default | Docs |
@@ -157,7 +167,7 @@ Specifies the action tenant
 
 | Name | Type | Default | Docs |
 |------|------|---------|------|
-| [`source`](#reactor-action-tenant-source){: #reactor-action-tenant-source .spark-required} | `Reactor.Template.Input \| Reactor.Template.Result \| Reactor.Template.Value` |  | What to use as the source of the tenant. See `Reactor.Dsl.Argument` for more information. |
+| [`source`](#reactor-action-tenant-source){: #reactor-action-tenant-source .spark-required} | `Reactor.Template.Input \| Reactor.Template.Result \| Reactor.Template.Value` |  | What to use as the source of the tenant. |
 ### Options
 
 | Name | Type | Default | Docs |
@@ -224,6 +234,16 @@ create name, resource, action \\ nil
 
 Declares a step that will call a create action on a resource.
 
+> #### Undo behaviour {: .tip}
+>
+> This step has three different modes of undo.
+>
+> * `never` - The result of the action is never undone.  This is the default.
+> * `always` - The `undo_action` will always be called.
+> * `outside_transaction` - The `undo_action` will not be called when running inside a `transaction` block, but will be otherwise.
+
+
+
 ### Nested DSLs
  * [actor](#reactor-create-actor)
  * [inputs](#reactor-create-inputs)
@@ -250,7 +270,7 @@ end
 
 | Name | Type | Default | Docs |
 |------|------|---------|------|
-| [`name`](#reactor-create-name){: #reactor-create-name .spark-required} | `atom` |  | A unique name for the step. This is used when choosing the return value of the Reactor and for arguments into other steps. |
+| [`name`](#reactor-create-name){: #reactor-create-name .spark-required} | `atom` |  | A unique name for the step. |
 | [`resource`](#reactor-create-resource){: #reactor-create-resource .spark-required} | `module` |  | The resource to call the action on. |
 | [`action`](#reactor-create-action){: #reactor-create-action } | `atom` |  | The name of the action to call on the resource. |
 ### Options
@@ -264,7 +284,7 @@ end
 | [`authorize?`](#reactor-create-authorize?){: #reactor-create-authorize? } | `boolean \| nil` |  | Explicitly enable or disable authorization for the action. |
 | [`description`](#reactor-create-description){: #reactor-create-description } | `String.t` |  | A description for the step |
 | [`undo_action`](#reactor-create-undo_action){: #reactor-create-undo_action } | `atom` |  | The name of the action to call on the resource when the step is to be undone. |
-| [`undo`](#reactor-create-undo){: #reactor-create-undo } | `:always \| :never \| :outside_transaction` | `:never` | What to do when the reactor is undoing it's work? * `always` - The undo action will always be run. * `never` - The action will never be undone. * `outside_transaction` - The action will only be undone if not running inside a transaction. |
+| [`undo`](#reactor-create-undo){: #reactor-create-undo } | `:always \| :never \| :outside_transaction` | `:never` | How to handle undoing this action |
 
 
 ## reactor.create.actor
@@ -283,7 +303,7 @@ Specifies the action actor
 
 | Name | Type | Default | Docs |
 |------|------|---------|------|
-| [`source`](#reactor-create-actor-source){: #reactor-create-actor-source .spark-required} | `Reactor.Template.Input \| Reactor.Template.Result \| Reactor.Template.Value` |  | What to use as the source of the actor. See `Reactor.Dsl.Argument` for more information. |
+| [`source`](#reactor-create-actor-source){: #reactor-create-actor-source .spark-required} | `Reactor.Template.Input \| Reactor.Template.Result \| Reactor.Template.Value` |  | What to use as the source of the actor. |
 ### Options
 
 | Name | Type | Default | Docs |
@@ -360,7 +380,7 @@ Specifies the action tenant
 
 | Name | Type | Default | Docs |
 |------|------|---------|------|
-| [`source`](#reactor-create-tenant-source){: #reactor-create-tenant-source .spark-required} | `Reactor.Template.Input \| Reactor.Template.Result \| Reactor.Template.Value` |  | What to use as the source of the tenant. See `Reactor.Dsl.Argument` for more information. |
+| [`source`](#reactor-create-tenant-source){: #reactor-create-tenant-source .spark-required} | `Reactor.Template.Input \| Reactor.Template.Result \| Reactor.Template.Value` |  | What to use as the source of the tenant. |
 ### Options
 
 | Name | Type | Default | Docs |
@@ -427,6 +447,16 @@ destroy name, resource, action \\ nil
 
 Declares a step that will call a destroy action on a resource.
 
+> #### Undo behaviour {: .tip}
+>
+> This step has three different modes of undo.
+>
+> * `never` - The result of the action is never undone.  This is the default.
+> * `always` - The `undo_action` will always be called.
+> * `outside_transaction` - The `undo_action` will not be called when running inside a `transaction` block, but will be otherwise.
+
+
+
 ### Nested DSLs
  * [actor](#reactor-destroy-actor)
  * [inputs](#reactor-destroy-inputs)
@@ -450,7 +480,7 @@ end
 
 | Name | Type | Default | Docs |
 |------|------|---------|------|
-| [`name`](#reactor-destroy-name){: #reactor-destroy-name .spark-required} | `atom` |  | A unique name for the step. This is used when choosing the return value of the Reactor and for arguments into other steps. |
+| [`name`](#reactor-destroy-name){: #reactor-destroy-name .spark-required} | `atom` |  | A unique name for the step. |
 | [`resource`](#reactor-destroy-resource){: #reactor-destroy-resource .spark-required} | `module` |  | The resource to call the action on. |
 | [`action`](#reactor-destroy-action){: #reactor-destroy-action } | `atom` |  | The name of the action to call on the resource. |
 ### Options
@@ -464,7 +494,7 @@ end
 | [`authorize?`](#reactor-destroy-authorize?){: #reactor-destroy-authorize? } | `boolean \| nil` |  | Explicitly enable or disable authorization for the action. |
 | [`description`](#reactor-destroy-description){: #reactor-destroy-description } | `String.t` |  | A description for the step |
 | [`undo_action`](#reactor-destroy-undo_action){: #reactor-destroy-undo_action } | `atom` |  | The name of the action to call on the resource when the step is to be undone. |
-| [`undo`](#reactor-destroy-undo){: #reactor-destroy-undo } | `:always \| :never \| :outside_transaction` | `:never` | What to do when the reactor is undoing it's work? * `always` - The undo action will always be run. * `never` - The action will never be undone. * `outside_transaction` - The action will only be undone if not running inside a transaction. |
+| [`undo`](#reactor-destroy-undo){: #reactor-destroy-undo } | `:always \| :never \| :outside_transaction` | `:never` | How to handle undoing this action |
 
 
 ## reactor.destroy.actor
@@ -483,7 +513,7 @@ Specifies the action actor
 
 | Name | Type | Default | Docs |
 |------|------|---------|------|
-| [`source`](#reactor-destroy-actor-source){: #reactor-destroy-actor-source .spark-required} | `Reactor.Template.Input \| Reactor.Template.Result \| Reactor.Template.Value` |  | What to use as the source of the actor. See `Reactor.Dsl.Argument` for more information. |
+| [`source`](#reactor-destroy-actor-source){: #reactor-destroy-actor-source .spark-required} | `Reactor.Template.Input \| Reactor.Template.Result \| Reactor.Template.Value` |  | What to use as the source of the actor. |
 ### Options
 
 | Name | Type | Default | Docs |
@@ -560,7 +590,7 @@ Specifies the action tenant
 
 | Name | Type | Default | Docs |
 |------|------|---------|------|
-| [`source`](#reactor-destroy-tenant-source){: #reactor-destroy-tenant-source .spark-required} | `Reactor.Template.Input \| Reactor.Template.Result \| Reactor.Template.Value` |  | What to use as the source of the tenant. See `Reactor.Dsl.Argument` for more information. |
+| [`source`](#reactor-destroy-tenant-source){: #reactor-destroy-tenant-source .spark-required} | `Reactor.Template.Input \| Reactor.Template.Result \| Reactor.Template.Value` |  | What to use as the source of the tenant. |
 ### Options
 
 | Name | Type | Default | Docs |
@@ -648,7 +678,7 @@ end
 
 | Name | Type | Default | Docs |
 |------|------|---------|------|
-| [`name`](#reactor-read_one-name){: #reactor-read_one-name .spark-required} | `atom` |  | A unique name for the step. This is used when choosing the return value of the Reactor and for arguments into other steps. |
+| [`name`](#reactor-read_one-name){: #reactor-read_one-name .spark-required} | `atom` |  | A unique name for the step. |
 | [`resource`](#reactor-read_one-resource){: #reactor-read_one-resource .spark-required} | `module` |  | The resource to call the action on. |
 | [`action`](#reactor-read_one-action){: #reactor-read_one-action } | `atom` |  | The name of the action to call on the resource. |
 ### Options
@@ -678,7 +708,7 @@ Specifies the action actor
 
 | Name | Type | Default | Docs |
 |------|------|---------|------|
-| [`source`](#reactor-read_one-actor-source){: #reactor-read_one-actor-source .spark-required} | `Reactor.Template.Input \| Reactor.Template.Result \| Reactor.Template.Value` |  | What to use as the source of the actor. See `Reactor.Dsl.Argument` for more information. |
+| [`source`](#reactor-read_one-actor-source){: #reactor-read_one-actor-source .spark-required} | `Reactor.Template.Input \| Reactor.Template.Result \| Reactor.Template.Value` |  | What to use as the source of the actor. |
 ### Options
 
 | Name | Type | Default | Docs |
@@ -755,7 +785,7 @@ Specifies the action tenant
 
 | Name | Type | Default | Docs |
 |------|------|---------|------|
-| [`source`](#reactor-read_one-tenant-source){: #reactor-read_one-tenant-source .spark-required} | `Reactor.Template.Input \| Reactor.Template.Result \| Reactor.Template.Value` |  | What to use as the source of the tenant. See `Reactor.Dsl.Argument` for more information. |
+| [`source`](#reactor-read_one-tenant-source){: #reactor-read_one-tenant-source .spark-required} | `Reactor.Template.Input \| Reactor.Template.Result \| Reactor.Template.Value` |  | What to use as the source of the tenant. |
 ### Options
 
 | Name | Type | Default | Docs |
@@ -848,7 +878,7 @@ end
 
 | Name | Type | Default | Docs |
 |------|------|---------|------|
-| [`name`](#reactor-read-name){: #reactor-read-name .spark-required} | `atom` |  | A unique name for the step. This is used when choosing the return value of the Reactor and for arguments into other steps. |
+| [`name`](#reactor-read-name){: #reactor-read-name .spark-required} | `atom` |  | A unique name for the step. |
 | [`resource`](#reactor-read-resource){: #reactor-read-resource .spark-required} | `module` |  | The resource to call the action on. |
 | [`action`](#reactor-read-action){: #reactor-read-action } | `atom` |  | The name of the action to call on the resource. |
 ### Options
@@ -877,7 +907,7 @@ Specifies the action actor
 
 | Name | Type | Default | Docs |
 |------|------|---------|------|
-| [`source`](#reactor-read-actor-source){: #reactor-read-actor-source .spark-required} | `Reactor.Template.Input \| Reactor.Template.Result \| Reactor.Template.Value` |  | What to use as the source of the actor. See `Reactor.Dsl.Argument` for more information. |
+| [`source`](#reactor-read-actor-source){: #reactor-read-actor-source .spark-required} | `Reactor.Template.Input \| Reactor.Template.Result \| Reactor.Template.Value` |  | What to use as the source of the actor. |
 ### Options
 
 | Name | Type | Default | Docs |
@@ -954,7 +984,7 @@ Specifies the action tenant
 
 | Name | Type | Default | Docs |
 |------|------|---------|------|
-| [`source`](#reactor-read-tenant-source){: #reactor-read-tenant-source .spark-required} | `Reactor.Template.Input \| Reactor.Template.Result \| Reactor.Template.Value` |  | What to use as the source of the tenant. See `Reactor.Dsl.Argument` for more information. |
+| [`source`](#reactor-read-tenant-source){: #reactor-read-tenant-source .spark-required} | `Reactor.Template.Input \| Reactor.Template.Result \| Reactor.Template.Value` |  | What to use as the source of the tenant. |
 ### Options
 
 | Name | Type | Default | Docs |
@@ -1031,7 +1061,7 @@ Creates a group of steps which will be executed inside a data layer transaction.
 
 | Name | Type | Default | Docs |
 |------|------|---------|------|
-| [`name`](#reactor-transaction-name){: #reactor-transaction-name .spark-required} | `atom` |  | A unique name for the step. This is used when choosing the return value of the Reactor and for arguments into other steps. |
+| [`name`](#reactor-transaction-name){: #reactor-transaction-name .spark-required} | `atom` |  | A unique name for the step. |
 | [`resources`](#reactor-transaction-resources){: #reactor-transaction-resources .spark-required} | `module \| list(module)` |  | A resource or list of resources to consider in the transaction. |
 ### Options
 
@@ -1093,6 +1123,16 @@ update name, resource, action \\ nil
 
 Declares a step that will call an update action on a resource.
 
+> #### Undo behaviour {: .tip}
+>
+> This step has three different modes of undo.
+>
+> * `never` - The result of the action is never undone.  This is the default.
+> * `always` - The `undo_action` will always be called.
+> * `outside_transaction` - The `undo_action` will not be called when running inside a `transaction` block, but will be otherwise.
+
+
+
 ### Nested DSLs
  * [actor](#reactor-update-actor)
  * [inputs](#reactor-update-inputs)
@@ -1119,7 +1159,7 @@ end
 
 | Name | Type | Default | Docs |
 |------|------|---------|------|
-| [`name`](#reactor-update-name){: #reactor-update-name .spark-required} | `atom` |  | A unique name for the step. This is used when choosing the return value of the Reactor and for arguments into other steps. |
+| [`name`](#reactor-update-name){: #reactor-update-name .spark-required} | `atom` |  | A unique name for the step. |
 | [`resource`](#reactor-update-resource){: #reactor-update-resource .spark-required} | `module` |  | The resource to call the action on. |
 | [`action`](#reactor-update-action){: #reactor-update-action } | `atom` |  | The name of the action to call on the resource. |
 ### Options
@@ -1132,7 +1172,7 @@ end
 | [`authorize?`](#reactor-update-authorize?){: #reactor-update-authorize? } | `boolean \| nil` |  | Explicitly enable or disable authorization for the action. |
 | [`description`](#reactor-update-description){: #reactor-update-description } | `String.t` |  | A description for the step |
 | [`undo_action`](#reactor-update-undo_action){: #reactor-update-undo_action } | `atom` |  | The name of the action to call on the resource when the step is to be undone. |
-| [`undo`](#reactor-update-undo){: #reactor-update-undo } | `:always \| :never \| :outside_transaction` | `:never` | What to do when the reactor is undoing it's work? * `always` - The undo action will always be run. * `never` - The action will never be undone. * `outside_transaction` - The action will only be undone if not running inside a transaction. |
+| [`undo`](#reactor-update-undo){: #reactor-update-undo } | `:always \| :never \| :outside_transaction` | `:never` | How to handle undoing this action |
 
 
 ## reactor.update.actor
@@ -1151,7 +1191,7 @@ Specifies the action actor
 
 | Name | Type | Default | Docs |
 |------|------|---------|------|
-| [`source`](#reactor-update-actor-source){: #reactor-update-actor-source .spark-required} | `Reactor.Template.Input \| Reactor.Template.Result \| Reactor.Template.Value` |  | What to use as the source of the actor. See `Reactor.Dsl.Argument` for more information. |
+| [`source`](#reactor-update-actor-source){: #reactor-update-actor-source .spark-required} | `Reactor.Template.Input \| Reactor.Template.Result \| Reactor.Template.Value` |  | What to use as the source of the actor. |
 ### Options
 
 | Name | Type | Default | Docs |
@@ -1228,7 +1268,7 @@ Specifies the action tenant
 
 | Name | Type | Default | Docs |
 |------|------|---------|------|
-| [`source`](#reactor-update-tenant-source){: #reactor-update-tenant-source .spark-required} | `Reactor.Template.Input \| Reactor.Template.Result \| Reactor.Template.Value` |  | What to use as the source of the tenant. See `Reactor.Dsl.Argument` for more information. |
+| [`source`](#reactor-update-tenant-source){: #reactor-update-tenant-source .spark-required} | `Reactor.Template.Input \| Reactor.Template.Result \| Reactor.Template.Value` |  | What to use as the source of the tenant. |
 ### Options
 
 | Name | Type | Default | Docs |
diff --git a/lib/ash/reactor/dsl/action.ex b/lib/ash/reactor/dsl/action.ex
index 9a387075..91996c17 100644
--- a/lib/ash/reactor/dsl/action.ex
+++ b/lib/ash/reactor/dsl/action.ex
@@ -44,7 +44,11 @@ defmodule Ash.Reactor.Dsl.Action do
   def __entity__,
     do: %Spark.Dsl.Entity{
       name: :action,
-      describe: "Declares a step that will call a generic action on a resource.",
+      describe: """
+      Declares a step that will call a generic action on a resource.
+
+      #{Ash.Reactor.Dsl.Action.__shared_undo_docs__()}
+      """,
       no_depend_modules: [:domain, :resource],
       target: __MODULE__,
       args: [:name, :resource, {:optional, :action}],
@@ -98,12 +102,7 @@ defmodule Ash.Reactor.Dsl.Action do
       name: [
         type: :atom,
         required: true,
-        doc: """
-        A unique name for the step.
-
-        This is used when choosing the return value of the Reactor and for
-        arguments into other steps.
-        """
+        doc: "A unique name for the step."
       ],
       resource: [
         type: {:spark, Ash.Resource},
@@ -126,19 +125,25 @@ defmodule Ash.Reactor.Dsl.Action do
           type: {:in, [:always, :never, :outside_transaction]},
           required: false,
           default: :never,
-          doc: """
-          What to do when the reactor is undoing it's work?
-
-          * `always` - The undo action will always be run.
-          * `never` - The action will never be undone.
-          * `outside_transaction` - The action will only be undone if not running inside a transaction.
-          """
+          doc: "How to handle undoing this action"
         ]
       ],
       include_undo?
     )
   end
 
+  def __shared_undo_docs__ do
+    """
+    > #### Undo behaviour {: .tip}
+    >
+    > This step has three different modes of undo.
+    >
+    > * `never` - The result of the action is never undone.  This is the default.
+    > * `always` - The `undo_action` will always be called.
+    > * `outside_transaction` - The `undo_action` will not be called when running inside a `transaction` block, but will be otherwise.
+    """
+  end
+
   defp maybe_concat(left, right, true), do: Enum.concat(left, right)
   defp maybe_concat(left, _right, _falsy), do: left
 end
diff --git a/lib/ash/reactor/dsl/actor.ex b/lib/ash/reactor/dsl/actor.ex
index 22a965f7..86ad1610 100644
--- a/lib/ash/reactor/dsl/actor.ex
+++ b/lib/ash/reactor/dsl/actor.ex
@@ -28,21 +28,15 @@ defmodule Ash.Reactor.Dsl.Actor do
         source: [
           type: template_type,
           required: true,
-          doc: """
-          What to use as the source of the actor.
-
-          See `Reactor.Dsl.Argument` for more information.
-          """
+          doc: "What to use as the source of the actor."
         ],
         transform: [
           type:
             {:or, [{:spark_function_behaviour, Reactor.Step, {Reactor.Step.Transform, 1}}, nil]},
           required: false,
           default: nil,
-          doc: """
-          An optional transformation function which can be used to modify the
-          actor before it is passed to the action.
-          """
+          doc:
+            "An optional transformation function which can be used to modify the actor before it is passed to the action."
         ]
       ]
     }
diff --git a/lib/ash/reactor/dsl/create.ex b/lib/ash/reactor/dsl/create.ex
index d05a8311..0476733c 100644
--- a/lib/ash/reactor/dsl/create.ex
+++ b/lib/ash/reactor/dsl/create.ex
@@ -48,7 +48,11 @@ defmodule Ash.Reactor.Dsl.Create do
   def __entity__,
     do: %Spark.Dsl.Entity{
       name: :create,
-      describe: "Declares a step that will call a create action on a resource.",
+      describe: """
+      Declares a step that will call a create action on a resource.
+
+      #{Ash.Reactor.Dsl.Action.__shared_undo_docs__()}
+      """,
       examples: [
         """
         create :create_post, MyApp.Post, :create do
diff --git a/lib/ash/reactor/dsl/destroy.ex b/lib/ash/reactor/dsl/destroy.ex
index 53e9e988..ffa2c5ed 100644
--- a/lib/ash/reactor/dsl/destroy.ex
+++ b/lib/ash/reactor/dsl/destroy.ex
@@ -48,7 +48,11 @@ defmodule Ash.Reactor.Dsl.Destroy do
   def __entity__,
     do: %Spark.Dsl.Entity{
       name: :destroy,
-      describe: "Declares a step that will call a destroy action on a resource.",
+      describe: """
+      Declares a step that will call a destroy action on a resource.
+
+      #{Ash.Reactor.Dsl.Action.__shared_undo_docs__()}
+      """,
       examples: [
         """
         destroy :delete_post, MyApp.Post, :destroy do
diff --git a/lib/ash/reactor/dsl/inputs.ex b/lib/ash/reactor/dsl/inputs.ex
index f356b667..f301685c 100644
--- a/lib/ash/reactor/dsl/inputs.ex
+++ b/lib/ash/reactor/dsl/inputs.ex
@@ -63,10 +63,8 @@ defmodule Ash.Reactor.Dsl.Inputs do
              [{:spark_function_behaviour, Reactor.Step, {Reactor.Step.TransformAll, 1}}, nil]},
           required: false,
           default: nil,
-          doc: """
-          An optional transformation function which will transform the inputs
-          before executing the action.
-          """
+          doc:
+            "An optional transformation function which will transform the inputs before executing the action."
         ]
       ],
       transform: {__MODULE__, :__transform__, []}
diff --git a/lib/ash/reactor/dsl/tenant.ex b/lib/ash/reactor/dsl/tenant.ex
index 3175bfb9..828caa9d 100644
--- a/lib/ash/reactor/dsl/tenant.ex
+++ b/lib/ash/reactor/dsl/tenant.ex
@@ -28,21 +28,15 @@ defmodule Ash.Reactor.Dsl.Tenant do
         source: [
           type: template_type,
           required: true,
-          doc: """
-          What to use as the source of the tenant.
-
-          See `Reactor.Dsl.Argument` for more information.
-          """
+          doc: "What to use as the source of the tenant."
         ],
         transform: [
           type:
             {:or, [{:spark_function_behaviour, Reactor.Step, {Reactor.Step.Transform, 1}}, nil]},
           required: false,
           default: nil,
-          doc: """
-          An optional transformation function which can be used to modify the
-          tenant before it is passed to the action.
-          """
+          doc:
+            "An optional transformation function which can be used to modify the tenant before it is passed to the action."
         ]
       ]
     }
diff --git a/lib/ash/reactor/dsl/transaction.ex b/lib/ash/reactor/dsl/transaction.ex
index 287cfcb5..e60998b9 100644
--- a/lib/ash/reactor/dsl/transaction.ex
+++ b/lib/ash/reactor/dsl/transaction.ex
@@ -50,12 +50,7 @@ defmodule Ash.Reactor.Dsl.Transaction do
         name: [
           type: :atom,
           required: true,
-          doc: """
-          A unique name for the step.
-
-          This is used when choosing the return value of the Reactor and for
-          arguments into other steps.
-          """
+          doc: "A unique name for the step."
         ],
         resources: [
           type: {:wrap_list, {:spark, Ash.Resource}},
diff --git a/lib/ash/reactor/dsl/update.ex b/lib/ash/reactor/dsl/update.ex
index 0f03fc1c..6c2bf739 100644
--- a/lib/ash/reactor/dsl/update.ex
+++ b/lib/ash/reactor/dsl/update.ex
@@ -46,7 +46,11 @@ defmodule Ash.Reactor.Dsl.Update do
   def __entity__,
     do: %Spark.Dsl.Entity{
       name: :update,
-      describe: "Declares a step that will call an update action on a resource.",
+      describe: """
+      Declares a step that will call an update action on a resource.
+
+      #{Ash.Reactor.Dsl.Action.__shared_undo_docs__()}
+      """,
       examples: [
         """
         update :publish_post, MyApp.Post, :update do