Apply suggestions from code review

Committing recommended changes. Will continue to work on others.

Co-authored-by: Ed Cormany <[email protected]>

api/docs/v2/basic_commands/liquids.rst

@@ -263,7 +263,13 @@ This example aspirates enough air to fill the remaining volume in a pipette::
 Detect Liquids
 ==============
 
-The :py:meth:`.InstrumentContext.detect_liquid_presence` method tells a Flex pipette to check for the presence of a liquid in a wellplate or reservoir. This method returns ``True`` if the pressure sensors in a pipette detect a liquid and ``False`` if the sensors do not. It will not raise an error or stop your protocol when the robot detects and empty well. Detection takes place during aspiration, but you don't need to aspirate to use ``detect_liquid_presence``. It's a standalone method that can be called when you just want to detect liquids only. See also :ref:`lpd`. 
+The :py:meth:`.InstrumentContext.detect_liquid_presence` method tells a Flex pipette to check for the presence of a liquid in a well plate or reservoir. This method returns ``True`` if the pressure sensors in the pipette detect a liquid and ``False`` if the sensors do not. It will not raise an error or stop your protocol when the robot detects an empty well. 
+
+You should generally detect liquid immediately after picking up a tip and before aspirating, but you don't need to aspirate to use ``detect_liquid_presence()``. It's a standalone method that can be called when you only want to detect liquid. 
+
+.. note::
+    Accurate liquid detection requires fresh, dry pipette tips.
+
 
 .. code-block:: python
 

api/docs/v2/pipettes/loading.rst

@@ -224,7 +224,7 @@ Liquid Presence Detection
 Liquid Presence Detection is a pressure-based feature that allows Opentrons Flex pipettes to detect the presence or absence of liquids in a well, reservoir, or other container. Liquid Presence Detection gives you the ability to identify, avoid, and recover from liquid-related protocol errors. You can enable this feature for an entire protocol run or toggle it on and off as required. Liquid Presence Detection works with Flex pipettes only and is disabled by default.
 
 .. note::
-    If your protocol uses :ref:`partial tip pickup <partial-tip-pickup>`, the pressure sensors for the Flex 8-Channel pipette are on channels 1 and 8. For the Flex 96-Channel Pipette, the pressure sensors are on channels 1 and 96.
+    If your protocol uses :ref:`partial tip pickup <partial-tip-pickup>`, the pressure sensors for the Flex 8-Channel pipette are on channels A1 and H1. For the Flex 96-Channel Pipette, the pressure sensors are on channels A1 and H12.
 
 .. versionadded:: 2.20
 
@@ -267,19 +267,19 @@ You can turn Liquid Presence Detection off and on throughout a protocol. To turn
 
 .. code-block:: python
     
-    pipette.pick_up_tip(tiprack2)
-    pipette.liquid_presence_detection=False  #Liquid Presence Detection off
-    pipette.aspirate(100, reservoir["A2"])
+    pipette.pick_up_tip()
+    pipette.liquid_presence_detection=False  # liquid presence detection off
+    pipette.aspirate(100, reservoir["A2"])  # aspirates immediately
 
 Going forward, the pipette will not perform a liquid check until you turn this feature back on. 
 
-To reactivate, add ``pipette.liquid_presence_detection=True`` at the point later in a protocol where it needs to be enabled, usually between picking up a new tip and aspirating a liquid.
+To reactivate, set ``liquid_presence_detection=True`` at the point later in the protocol where it needs to be enabled, usually between picking up a new tip and aspirating a liquid.
 
 .. code-block:: python
 
-    pipette.pick_up_tip(tiprack2)
-    pipette.liquid_presence_detection=True  #Liquid Presence Detection on again
-    pipette.aspirate(100, reservoir["A3"])
+    pipette.pick_up_tip()
+    pipette.liquid_presence_detection=True  # liquid presence detection on again
+    pipette.aspirate(100, reservoir["A3"])  # detects liquid before aspirating
 
 The robot will continue to check for a liquid until this feature is disabled again, or an empty well is detected (and the robot raises an error), or the protocol completes.
 

api/src/opentrons/protocol_api/instrument_context.py

@@ -2120,7 +2120,9 @@ def configure_nozzle_layout(  # noqa: C901
 
     @requires_version(2, 20)
     def detect_liquid_presence(self, well: labware.Well) -> bool:
-        """Checks if there is liquid in a well. Will not raise an error if it does not detect liquid. Flex pipettes only. See :ref:`lpd` and :ref:`detect-liquid-presence`.
+        """Check if there is liquid in a well. 
+        
+        Returns ``True`` if liquid is present and ``False`` if liquid is not present. Will not raise an error if it does not detect liquid. Flex pipettes only. See :ref:`detect-liquid-presence`.
 
         When simulating a protocol, the check always succeeds (returns ``True``).
 
@@ -2132,7 +2134,11 @@ def detect_liquid_presence(self, well: labware.Well) -> bool:
 
     @requires_version(2, 20)
     def require_liquid_presence(self, well: labware.Well) -> None:
-        """Checks for liquid in a well. Raises an error if no liquid is detected. Flex pipettes only. See :ref:`lpd` and :ref:`require-liquid-presence`.
+        """Check for liquid in a well and raise an error if none is detected. 
+        
+        When this method raises an error, Flex will offer the opportunity to enter recovery mode. In recovery mode, you can manually add liquid to resolve the error. 
+        
+        Works with Flex pipettes only. See :ref:`lpd` and :ref:`require-liquid-presence`.
 
         When simulating a protocol, the check always succeeds (does not raise an error).
 

api/src/opentrons/protocol_api/protocol_context.py

@@ -906,7 +906,7 @@ def load_instrument(
                              control <advanced-control>` applications. You cannot
                              replace an instrument in the middle of a protocol being run
                              from the Opentrons App or touchscreen.
-        :param bool liquid_presence_detection: If ``True``, enables liquid presence detection for Flex 1-, 8-, or 96-channel pipettes. See :ref:`lpd`.
+        :param bool liquid_presence_detection: If ``True``, enable liquid presence detection for Flex 1-, 8-, or 96-channel pipettes. See :ref:`lpd`.
 
                     .. versionadded:: 2.20
         """