From 1b7a7341e1a8385ea5e29b159c1102e64fc00ddb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jos=C3=A9=20Valim?= <jose.valim@dashbit.co>
Date: Wed, 29 May 2024 10:21:06 +0200
Subject: [PATCH] Improve ExUnit Callbacks docs

---
 lib/ex_unit/lib/ex_unit/callbacks.ex        | 21 ++++++++++++---------
 lib/ex_unit/test/ex_unit/callbacks_test.exs |  4 ++--
 2 files changed, 14 insertions(+), 11 deletions(-)

diff --git a/lib/ex_unit/lib/ex_unit/callbacks.ex b/lib/ex_unit/lib/ex_unit/callbacks.ex
index 2669bb4d9a1..782c352bccd 100644
--- a/lib/ex_unit/lib/ex_unit/callbacks.ex
+++ b/lib/ex_unit/lib/ex_unit/callbacks.ex
@@ -3,8 +3,9 @@ defmodule ExUnit.Callbacks do
   Defines ExUnit callbacks.
 
   This module defines the `setup/1`, `setup/2`, `setup_all/1`, and
-  `setup_all/2` callbacks, as well as the `on_exit/2`, `start_supervised/2`,
-  `stop_supervised/1` and `start_link_supervised!/2` functions.
+  `setup_all/2` macros, as well as process lifecycle and management
+  functions, such as `on_exit/2`, `start_supervised/2`, `stop_supervised/1`
+  and `start_link_supervised!/2`.
 
   The setup callbacks may be used to define [test fixtures](https://en.wikipedia.org/wiki/Test_fixture#Software)
   and run any initialization code which help bring the system into a known
@@ -56,13 +57,15 @@ defmodule ExUnit.Callbacks do
 
   ## Context
 
-  If `setup_all` or `setup` return a keyword list, a map, or a tuple in the shape
-  of `{:ok, keyword() | map()}`, the keyword list or map will be merged into the
-  current context and will be available in all subsequent `setup_all`,
-  `setup`, and the `test` itself.
+  `setup_all` or `setup` may return one of:
 
-  Returning `:ok` leaves the context unchanged (in `setup` and `setup_all`
-  callbacks).
+    * the atom `:ok`
+    * a keyword list or map
+    * a tuple in the shape of `{:ok, keyword() | map()}`
+
+  If a keyword list or map is returned, it be merged into the current context
+  and will be available in all subsequent `setup_all`, `setup`, and the `test`
+  itself.
 
   Returning anything else from `setup_all` will force all tests to fail,
   while a bad response from `setup` causes the current test to fail.
@@ -728,7 +731,7 @@ defmodule ExUnit.Callbacks do
 
   defp raise_merge_failed!(mod, kind, return_value) do
     raise "expected ExUnit #{kind} callback in #{inspect(mod)} to " <>
-            "return :ok | keyword | map, got #{inspect(return_value)} instead"
+            "return the atom :ok, a keyword, or a map, got #{inspect(return_value)} instead"
   end
 
   defp raise_merge_reserved!(mod, kind, key, value) do
diff --git a/lib/ex_unit/test/ex_unit/callbacks_test.exs b/lib/ex_unit/test/ex_unit/callbacks_test.exs
index d799fc5e352..7778b8ceb65 100644
--- a/lib/ex_unit/test/ex_unit/callbacks_test.exs
+++ b/lib/ex_unit/test/ex_unit/callbacks_test.exs
@@ -394,7 +394,7 @@ defmodule ExUnit.CallbacksTest do
 
     assert output =~
              "** (RuntimeError) expected ExUnit setup callback in " <>
-               "ExUnit.CallbacksTest.SetupErrorTest to return :ok | keyword | map, " <>
+               "ExUnit.CallbacksTest.SetupErrorTest to return the atom :ok, a keyword, or a map, " <>
                "got {:ok, \"foo\"} instead"
 
     # Make sure that at least the right file where the setup/setup_all call is defined is included
@@ -414,7 +414,7 @@ defmodule ExUnit.CallbacksTest do
 
     assert output =~
              "** (RuntimeError) expected ExUnit setup_all callback in " <>
-               "ExUnit.CallbacksTest.SetupAllErrorTest to return :ok | keyword | map, " <>
+               "ExUnit.CallbacksTest.SetupAllErrorTest to return the atom :ok, a keyword, or a map, " <>
                "got {:ok, \"foo\"} instead"
 
     # Make sure that at least the right file where the setup/setup_all call is defined is included