Add typedocs for Worker.return/0 type (#1108)

Explain all of the return types and indicate that :discard is deprecated. --------- Co-authored-by: Parker Selbert <[email protected]>
sorentwo · Jun 21, 2024 · d9ca12b · d9ca12b
1 parent 160cc3a
commit d9ca12b
Showing 1 changed file with 16 additions and 0 deletions.
diff --git a/lib/oban/worker.ex b/lib/oban/worker.ex
@@ -257,6 +257,22 @@ defmodule Oban.Worker do
   alias Oban.{Backoff, Job, Validation}
 
   @type t :: module()
+
+  @typedoc """
+  Return values control whether a job is treated as a success or a failure.
+
+  - `:ok` - the job is successful and marked as `completed`.
+  - `{:ok, ignored}` - the job is successful, marked as `completed`, and the return value is ignored.
+  - `{:cancel, reason}` - the job is marked as `cancelled` for the provided reason and no longer retried.
+  - `{:error, reason}` - the job is marked as `retryable` for the provided reason, or `discarded`
+    if it has  exhausted all attempts.
+  - `{:snooze, seconds}` - mark the job as `scheduled` to run again `seconds` in the future.
+
+  > #### Deprecated {: .warning}
+  >
+  > - `:discard` - deprecated, use `{:cancel, reason}` instead.
+  > - `{:discard, reason}` - deprecated, use `{:cancel, reason}` instead.
+  """
   @type result ::
           :ok
           | :discard