Add resolve_pin() docstring and loop labels example

- Document return contract, resolution precedence, and type-sensitivity
  note in resolve_pin() docstring
- Add ex17_loop_labels.yml: RS-232 loopback adapter demonstrating
  loops with pin labels, mixed number+label, and label-based connections

examples/ex17_loop_labels.yml

@@ -0,0 +1,23 @@
+# Connector loops using pin labels
+# RS-232 loopback adapter: RTS-CTS and DSR-DTR-DCD jumpered,
+# with TX/RX/GND passed through to a cable.
+
+connectors:
+  X1:
+    type: D-Sub
+    subtype: female
+    pinlabels: [DCD, RX, TX, DTR, GND, DSR, RTS, CTS, RI]
+    loops:
+      - [RTS, CTS]      # pin labels instead of numbers
+      - [DSR, DTR]
+      - [4, DCD]         # mixed: pin number + label
+
+cables:
+  W1:
+    wirecount: 3
+    colors: [BK, RD, GN]
+
+connections:
+  -
+    - X1: [RX, TX, GND]  # labels in connections too
+    - W1: [1-3]

src/wireviz/DataClasses.py

@@ -227,8 +227,22 @@ class Connector:
     def resolve_pin(self, pin: Pin) -> Pin:
         """Resolve a pin identifier to its canonical pin number.
 
-        Accepts pin numbers (from self.pins) or pin labels (from
+        Given a value that may be either a pin number (from self.pins)
-        self.pinlabels). Raises if ambiguous or not found.
+        or a pin label (from self.pinlabels), returns the corresponding
+        pin number from self.pins.
+
+        Callers needing a positional index should use
+        self.pins.index(return_value).
+
+        Resolution order:
+            1. Value in both pins and pinlabels at the same position
+               -> return directly (no ambiguity).
+            2. Value in both at different positions -> raise.
+            3. Value only in pinlabels -> return corresponding pin number.
+            4. Value only in pins -> return directly.
+            5. Not found -> raise.
+
+        Note: Lookups are type-sensitive (int 1 != str "1").
         """
         in_pins = pin in self.pins
         in_labels = pin in self.pinlabels if self.pinlabels else False