docs/guides/callbacks.md in wayfarer-0.4.0 vs docs/guides/callbacks.md in wayfarer-0.4.1

@@ -1,32 +1,58 @@
 # Callbacks
 
-## Life cycle callbacks
+## Active Job callbacks
 
-Wayfarer supports all of Active Job's life cycle callbacks:
+Wayfarer naturally supports all of [Active Job's life cycle callbacks](https://edgeguides.rubyonrails.org/active_job_basics.html#callbacks).
 
-* [Active Job Basics: Callbacks](https://edgeguides.rubyonrails.org/active_job_basics.html#callbacks)
-* [ActiveJob::Callbacks](https://api.rubyonrails.org/classes/ActiveJob/Callbacks/ClassMethods.html)
+## `before_fetch`
 
-## `after_batch` callbacks
+Runs before a job fetches a page, either by making an HTTP request, or by
+navigating a browser to its task URL.
 
-Jobs can register callbacks to run once all jobs in their batch have concluded:
+```ruby
+class DummyJob < Wayfarer::Base
+  before_fetch :do_something
 
+  private
+
+  def do_something
+    # before the task.url is fetched
+  end
+end
+```
+
+## `before_action`
+
+Runs after a page was fetched, before an action method is called.
+
 ```ruby
 class DummyJob < Wayfarer::Base
-  after_batch do
-    # All jobs in batch done
+  before_action :do_something
+
+  private
+
+  def do_something
+    # page is available at this point
   end
+end
+```
 
+## `after_batch`
+
+Runs once the last job in a batch performed:
+
+```ruby
+class DummyJob < Wayfarer::Base
   after_batch do
-    # Multiple callbacks can be registered
+    # All jobs in batch done
   end
 end
 ```
 
 Internally, a batch counter is in-/decremented on certain events. Once the
-counter reaches zero, `after_batch` callbacks execute in declaration order.
+counter reaches zero, `after_batch` callbacks runs in declaration order.
 
 The counter is incremented when:
 
 * A job is enqueued within the batch.
 
@@ -34,5 +60,86 @@
 
 * A job succeeds.
 * A job fails due to an unhandled exception.
 * A job fails due to a discarded exception.
 * A job fails and thereyby exhausts its maximum attempts.
+
+!!! attention "Batch callbacks can fail jobs"
+
+    If the last job's `after_batch` callbacks raises an exception, this can lead
+    to the job getting retried. If the exception raised by the callback is
+    unhandled or discarded, the callback never fully runs.
+
+## Callback options
+
+### Definition styles
+
+Callbacks can be registered either by supplying a block or a symbol identifying
+a callback instance method:
+
+```ruby
+class DummyJob < Wayfarer::Base
+  before_action do
+    # ...
+  end
+
+  before_action :my_callback
+
+  private
+
+  def my_callback
+    # ...
+  end
+end
+```
+
+### Conditionals
+
+Callbacks can be registered conditionally with the `:if` and `:unless` keywords:
+
+```ruby
+class DummyJob < Wayfarer::Base
+  before_fetch :my_callback, if: :my_condition
+
+  private
+
+  def my_callback
+  end
+
+  def my_condition
+  end
+end
+```
+
+Callbacks can be registered for certain action methods only with the `:only` and
+`:except` keywords:
+
+```ruby
+class DummyJob < Wayfarer::Base
+  before_fetch :do_something, only: :foo
+
+  before_fetch except: [:foo, :qux] do
+    # runs only before bar
+  end
+
+  def foo
+  end
+
+  def bar
+  end
+end
+
+```
+
+### Early termination
+
+Callbacks that return `false` halt the callback chain:
+
+```ruby
+class DummyJob < Wayfarer::Base
+  before_action { false }
+
+  before_action do
+    # never runs
+  end
+end
+```