Apply suggestions from code review

Co-authored-by: Sai Kishor Kothakota <[email protected]>

doc/debugging.rst

@@ -1,33 +1,32 @@
 Debugging
 ^^^^^^^^^
 
-All controllers and hardware components are plugins that are loaded into the ``controller_manager``. Therefore the debugger needs to be attached to the controller_manager.
+All controllers and hardware components are plugins loaded into the ``controller_manager``. Therefore, the debugger must be attached to the ``controller_manager``. If multiple ``controller_manager`` instances are running on your robot or machine, you need to attach the debugger to the ``controller_manager`` associated with the hardware component or controller you want to debug.
 
 How-To
 ******************
 
-* Install xterm, gdb and gdbserver on your system
+* Install ``xterm``, ``gdb`` and ``gdbserver`` on your system
 
   .. code-block:: bash
 
     sudo apt install xterm gdb gdbserver
 
 * Make sure you run a "debug" or "release with debug information" build:
-  This is done by passing ``--cmake-args -DCMAKE_BUILD_TYPE=RelWithDebInfo`` to colcon build.
+  This is done by passing ``--cmake-args -DCMAKE_BUILD_TYPE=RelWithDebInfo`` to ``colcon build``.
   Remember that in release builds some breakpoints might not behave as you expect as the the corresponding line might have been optimized by the compiler. For such cases, a full Debug build (``--cmake-args -DCMAKE_BUILD_TYPE=Debug``) is recommended.
 
 * Adapt the launch file to run the controller manager with the debugger attached:
 
-  * Version A: Run it directly with the gdb cli:
+  * Version A: Run it directly with the gdb CLI:
 
     Add ``prefix=['xterm -e gdb -ex run --args']`` to the ``controller_manager`` node entry in your launch file.
-    Due to the way ros2launch works we need to run the specific node in a separate terminal instance.
-    See a gdb cli tutorial for further steps.
+    Due to how ``ros2launch`` works we need to run the specific node in a separate terminal instance.
 
   * Version B: Run it with gdbserver:
 
     Add ``prefix=['gdbserver localhost:3000']`` to the ``controller_manager`` node entry in your launch file.
-    Afterwards, you can either attach a gdb CLI instance or any IDE of your choice to that gdbserver instance.
+    Afterwards, you can either attach a gdb CLI instance or any IDE of your choice to that ``gdbserver`` instance.
     Ensure you start your debugger from a terminal where you have sourced your workspace to properly resolve all paths.
 
   Example launch file entry:
@@ -61,13 +60,13 @@ Additional notes
 
 * Debug builds
 
-  It often makes sense to only build the package you want to debug with debug information.
+  It's often practical to include debug information only for the specific package you want to debug.
   ``colcon build --packages-select [package_name] --cmake-args -DCMAKE_BUILD_TYPE=RelWithDebInfo`` or ``colcon build --packages-select [package_name] --cmake-args -DCMAKE_BUILD_TYPE=Debug``
 
 * Realtime
 
-  The ``update/on_activate`` method of a controller and the ``read/write/on_activate/perform_command_mode_switch`` methods of a hardware component all run in the context
-  of the realtime update loop. Setting breakpoints there can and will cause issues which might even break your hardware in the worst case.
+.. warning::
+  The ``update/on_activate/on_deactivate`` method of a controller and the ``read/write/on_activate/perform_command_mode_switch`` methods of a hardware component all run in the context of the realtime update loop. Setting breakpoints there can and will cause issues that might even break your hardware in the worst case.
 
 From experience, it might be better to use meaningful logs for the real-time context (with caution) or to add additional debug state interfaces (or publishers in the case of a controller).