improved block docs (#43611)

* improved block docs

 - broke down examples per keyword
 - clarified which errors are handled
 - clarified forcing error in rescue

changelogs/fragments/blockdoc.yml

@@ -0,0 +1,2 @@
+bugfixes:
+    - improved block docs

docs/docsite/rst/user_guide/playbooks_blocks.rst

@@ -43,35 +43,78 @@ Error Handling
 ``````````````
 
 Blocks also introduce the ability to handle errors in a way similar to exceptions in most programming languages.
+Blocks only deal with 'failed' status of a task. A bad task definition, an undefined variable or an unreachable host are not `rescuable`  errors.
 
+.. _block_rescue:
 .. code-block:: YAML
- :emphasize-lines: 3,9,15
+ :emphasize-lines: 3,10
  :caption: Block error handling example
 
-
   tasks:
-  - name: Attempt and graceful roll back demo
+  - name: Handle the error
     block:
       - debug:
           msg: 'I execute normally'
-      - command: /bin/false
+      - name: i force a failure
+        command: /bin/false
       - debug:
-          msg: 'I never execute, due to the above task failing'
+          msg: 'I never execute, due to the above task failing, :-('
     rescue:
       - debug:
-          msg: 'I caught an error'
+          msg: 'I caught an error, can do stuff here to fix it, :-)'
-      - command: /bin/false
+
+This will 'revert' the failed status of the task for the run and the play will continue as if it had succeeded.
+
+There is also an ``always`` section, that will run no matter what the task status is.
+
+.. _block_always:
+.. code-block:: YAML
+ :emphasize-lines: 2,9
+ :caption: Block with always section
+
+  - name: Always do X
+    block:
       - debug:
-          msg: 'I also never execute :-('
+          msg: 'I execute normally'
+      - name: i force a failure
+        command: /bin/false
+      - debug:
+          msg: 'I never execute :-('
     always:
       - debug:
-          msg: "This always executes"
+          msg: "This always executes, :-)"
+
+They can be added all together to do complex error handling.
+
+.. code-block:: YAML
+ :emphasize-lines: 2,9,16
+ :caption: Block with all sections
+
+ - name: Attempt and graceful roll back demo
+   block:
+     - debug:
+         msg: 'I execute normally'
+     - name: i force a failure
+       command: /bin/false
+     - debug:
+         msg: 'I never execute, due to the above task failing, :-('
+   rescue:
+     - debug:
+         msg: 'I caught an error'
+     - name: i force a failure in middle of recovery! >:-)
+       command: /bin/false
+     - debug:
+         msg: 'I also never execute :-('
+   always:
+     - debug:
+         msg: "This always executes"
+
 
 The tasks in the ``block`` would execute normally, if there is any error the ``rescue`` section would get executed
-with whatever you need to do to recover from the previous error. The ``always`` section runs no matter what previous
+with whatever you need to do to recover from the previous error.
-error did or did not occur in the ``block`` and ``rescue`` sections. It should be noted that the play continues if a
+The ``always`` section runs no matter what previous error did or did not occur in the ``block`` and ``rescue`` sections.
-``rescue`` section completes successfully as it 'erases' the error status (but not the reporting), this means it won't trigger ``max_fail_percentage`` nor ``any_errors_fatal`` configurations but will appear in the playbook statistics.
+It should be noted that the play continues if a ``rescue`` section completes successfully as it 'erases' the error status (but not the reporting),
-
+this means it won't trigger ``max_fail_percentage`` nor ``any_errors_fatal`` configurations but will appear in the playbook statistics.
 
 Another example is how to run handlers after an error occurred :