fix: multi-line DSL doc options in Ash.Reactor. (#974)

Closes #973.

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

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."
         ]
       ]
     }

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

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

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__, []}

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."
         ]
       ]
     }

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}},

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