docs(api): liquid classes docstrings and descriptions updates (#18996)

# Overview

Fixes some docstrings in liquid-class related functions and some
descriptions of the liquid class schema fields.

## Changelog

- Docstring updates for:
- `transfer_with_liquid_class`, `consolidate_with_liquid_class`,
`distribute_with_liquid_class`
  - `get_liquid_class`, `define_liquid_class`
- Liquid classes json schema field descriptions

## Risk assessment

None. Docs fixes only

---------

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

Author: sanni-t

api/src/opentrons/protocol_api/instrument_context.py

@@ -1801,9 +1801,6 @@ def transfer_with_liquid_class(
     ) -> InstrumentContext:
         """Move a particular type of liquid from one well or group of wells to another.
 
-        ..
-            This is intended for Opentrons internal use only and is not a guaranteed API.
-
         :param liquid_class: The type of liquid to move. You must specify the liquid class,
             even if you have used :py:meth:`.Labware.load_liquid` to indicate what liquid the
             source contains.
@@ -1944,16 +1941,12 @@ def distribute_with_liquid_class(
         """
         Distribute a particular type of liquid from one well to a group of wells.
 
-        ..
-            This is intended for Opentrons internal use only and is not a guaranteed API.
-
         :param liquid_class: The type of liquid to move. You must specify the liquid class,
             even if you have used :py:meth:`.Labware.load_liquid` to indicate what liquid the
             source contains.
         :type liquid_class: :py:class:`.LiquidClass`
 
-        :param volume: The amount, in µL, to aspirate from the source and dispense to
-                       each destination.
+        :param volume: The amount, in µL, to dispense to each destination.
         :param source: A single well for the pipette to target, or a group of wells to
                        target in a single aspirate for a multi-channel pipette.
         :param dest: A list of wells to dispense liquid into.
@@ -2092,16 +2085,12 @@ def consolidate_with_liquid_class(
         """
         Consolidate a particular type of liquid from a group of wells to one well.
 
-        ..
-            This is intended for Opentrons internal use only and is not a guaranteed API.
-
         :param liquid_class: The type of liquid to move. You must specify the liquid class,
             even if you have used :py:meth:`.Labware.load_liquid` to indicate what liquid the
             source contains.
         :type liquid_class: :py:class:`.LiquidClass`
 
-        :param volume: The amount, in µL, to aspirate from the source and dispense to
-                       each destination.
+        :param volume: The amount, in µL, to aspirate from each source well.
         :param source: A list of wells to aspirate liquid from.
         :param dest: A single well, list of wells, trash bin, or waste chute to dispense liquid into.
                      Multiple wells can only be given for multi-channel pipette configurations, and

api/src/opentrons/protocol_api/protocol_context.py

@@ -1386,6 +1386,8 @@ def get_liquid_class(
             - ``"ethanol_80"``: an Opentrons-verified liquid class for volatile liquid. Based on 80% ethanol.
 
         :raises: ``LiquidClassDefinitionDoesNotExist``: if the specified liquid class does not exist.
+
+        :returns: A new LiquidClass object.
         """
         return self._core.get_liquid_class(name=name, version=DEFAULT_LC_VERSION)
 
@@ -1397,15 +1399,16 @@ def define_liquid_class(
         base_liquid_class: Optional[LiquidClass] = None,
         display_name: Optional[str] = None,
     ) -> LiquidClass:
-        """Define a custom liquid class, either based on an existing, Opentrons-verified liquid class, or to create a completely new one.
+        """Define a custom liquid class, either based on an existing liquid class, or create a completely new one.
 
         :param name: The name to give to the new liquid class. Cannot use the name of an Opentrons-verified liquid class.
-        :param properties: A dict of transfer properties for the Flex pipette and tips to use for liquid class transfers. The nested dictionary must have top-level keys corresponding to pipette load names and second-level keys corresponding to compatible tip rack load names. Further nested key–value pairs should be in the format returned by :py:meth:`.LiquidClass.get_for`. See also the `liquid class JSON schema <https://github.com/Opentrons/opentrons/tree/edge/shared-data/liquid-class/schemas>`_.
+        :param properties: A dict of transfer properties for pipette and tip combinations to use for liquid class transfers. The nested dictionary must have top-level keys corresponding to pipette load names and second-level keys corresponding to compatible tip rack load names. Further nested key–value pairs should be as specified in ``TransferPropertiesDict``. See the  `liquid class type definitions <https://github.com/Opentrons/opentrons/blob/edge/shared-data/python/opentrons_shared_data/liquid_classes/types.py>`_.
 
-        :param base_liquid_class: An Opentrons-verified liquid class to base the newly defined liquid class on. The specified ``transfer_properties`` will override any existing properties for the Flex pipette and tips. All other properties will remain the same as those in the base class.
+        :param base_liquid_class: An existing liquid class object to base the newly defined liquid class on. The specified ``transfer_properties`` will override any existing properties for the specified pipette and tip combinations. All other properties will remain the same as those in the base class.
 
         :param display_name: An optional name for the liquid class. Defaults to the title-case ``name`` if a display name isn't provided.
 
+        :returns: A new LiquidClass object.
         """
         if definition_exists(name, DEFAULT_LC_VERSION):
             raise ValueError(

shared-data/liquid-class/schemas/1.json

@@ -105,7 +105,7 @@
     },
     "airGapByVolume": {
       "type": "array",
-      "description": "Settings for air gap keyed by target aspiration volume.",
+      "description": "Settings for air gap keyed by current volume in the tip.",
       "items": {
         "type": "array",
         "items": { "$ref": "#/definitions/positiveNumber" },
@@ -127,7 +127,7 @@
     },
     "pushOutByVolume": {
       "type": "array",
-      "description": "Settings for pushout keyed by target aspiration volume.",
+      "description": "Settings for pushout keyed by target dispense volume.",
       "items": {
         "type": "array",
         "items": { "$ref": "#/definitions/positiveNumber" },
@@ -138,7 +138,7 @@
     },
     "disposalByVolume": {
       "type": "array",
-      "description": "An array of two tuples containing positive numbers.",
+      "description": "Settings for disposal volume, keyed by the total volume aspirated for a multi-dispense.",
       "items": {
         "type": "array",
         "items": { "$ref": "#/definitions/positiveNumber" },
@@ -149,7 +149,7 @@
     },
     "conditioningByVolume": {
       "type": "array",
-      "description": "Settings for conditioning volume keyed by target dispense volume.",
+      "description": "Settings for conditioning volume keyed by the total volume aspirated for a multi-dispense.",
       "items": {
         "type": "array",
         "items": { "$ref": "#/definitions/positiveNumber" },
@@ -160,7 +160,7 @@
     },
     "correctionByVolume": {
       "type": "array",
-      "description": "Settings for volume correction keyed by target aspiration/dispense volume, representing additional volume the plunger should move to accurately hit target volume.",
+      "description": "Settings for volume correction, keyed by the total volume in tip after the aspirate/dispense action. The correction value provides additional information about how much the pipette plunger should move to accurately pipette the specified volume when using this liquid class.",
       "items": {
         "type": "array",
         "items": { "type": "number" },
@@ -211,7 +211,7 @@
             "location": {
               "type": "string",
               "enum": ["source", "destination", "trash"],
-              "description": "Location well or trash entity for blow out."
+              "description": "Location for blow out."
             },
             "flowRate": {
               "$ref": "#/definitions/positiveNumber",
@@ -244,7 +244,7 @@
     },
     "retractAspirate": {
       "type": "object",
-      "description": "Shared properties for the retract function after aspiration or dispense.",
+      "description": "Shared properties for the retract function after an aspiration.",
       "properties": {
         "endPosition": {
           "$ref": "#/definitions/tipPosition"
@@ -268,7 +268,7 @@
     },
     "retractDispense": {
       "type": "object",
-      "description": "Shared properties for the retract function after aspiration or dispense.",
+      "description": "Shared properties for the retract function after a dispense.",
       "properties": {
         "endPosition": {
           "$ref": "#/definitions/tipPosition"