a little more docs on val_mapping

qcodes/instrument/parameter.py

@@ -211,8 +211,10 @@ def __init__(self, instrument, name,
 
         val_mapping: a bidirectional map from data/readable values to
             instrument codes, expressed as a dict.
-            For example, if '0' means 1V and '1' means 10V,
-            set val_mapping={1: '0', 10: '1'}.
+            For example, if the instrument uses '0' to mean 1V and '1' to mean
+            10V, set val_mapping={1: '0', 10: '1'} and on the user side you
+            only see 1 and 10, never the coded '0' and '1'
+
             If vals is omitted, will also construct a matching Enum validator.
             NOTE: only applies to get if get_cmd is a string, and to set if
             set_cmd is a string.

qcodes/tests/test_instrument.py

@@ -301,9 +301,13 @@ def test_val_mapping(self):
         gates = self.gates
         mem = self.model._memory
 
+        # memraw has no mappings - it just sets and gets what the instrument
+        # uses to encode this parameter
         gates.add_parameter('memraw', set_cmd='mem0 {}', get_cmd='mem0?',
                             vals=Enum('zero', 'one'))
 
+        # memcoded maps the instrument codes ('zero' and 'one') into nicer
+        # user values 0 and 1
         gates.add_parameter('memcoded', set_cmd='mem0 {}', get_cmd='mem0?',
                             val_mapping={0: 'zero', 1: 'one'})