Fully describe behavior of Pin.value() and Pin.value(x) in different modes, as well as clarificatiosn for other Pin methods.

Hardware-API.md

@@ -147,19 +147,24 @@ As specified above, Pin class allows to set alternate function for particular pi
 
 ### Methods
 
-Do we really need 3 ways to set the value?
+TOD: Do we really need 2+ ways to set the value?
 
-- `pin.init(...)`  re init.
-- `pin.value()` NOHEAP; get value (returns 1 or 0). See the note below.
-- `pin.value(x)` NOHEAP; set value (value can be any valid Boolean expression)
-- `pin()` NOHEAP; fast method to get the value of the pin. See the note below.
-- `pin(value)` NOHEAP; fast method to set the value of the pin.
-- `pin.toggle()` NOHEAP
-
-**Note:** When the mode is `Pin.OPEN_DRAIN`, it must be possible to read the input value of the Pin.
+- `pin.init(...)` - (Re)initinialize a pin, accepts the same parameters as constructor, except `id`.
+- `pin.value()` NOHEAP - Get pin value (returns 1 or 0). Behavior depends on the mode of a pin:
+  - `Pin.IN` - Returns the actual input value currently present on a pin.
+  - `Pin.OUT` - Undefined. MAY return value stored in the output buffer of a pin.
+  - `Pin.OPEN_DRAIN` - If pin is in "0" state, undefined. MAY return value stored in the output buffer of a pin (i.e. 0). Or MAY return actual input value on a pin. Otherwise, if pin is in "1", MUST return actual input value on a pin. (Note that if open-drain pin is in 0 state, entire bus to which pin is connected, expected to be in 0 state, so there's little point to read actual input value; the only reason for another value in this case would be voltage conflict on a bus, which is usually a hardware malfunction and in some cases may lead to physical damage of a pin).
+- `pin.value(x)` NOHEAP - Set output value of a pin (value can be any valid expression, which is cast to True/False valur for 1/0 output value respectively). Exact behavior depends on the pin mode:
+  - `Pin.IN` - Value is stored in the output buffer for a pin. Pin state doesn't change (it keeps being in high-impedance state, as required for IN mode). The stored value will become active on a pin as soon as it is changed to OUT or OPEN_DRAIN mode.
+  - `Pin.OUT` - Pin is set to the `x` value immediately.
+  - `Pin.OPEN_DRAIN` - If value is "0", ping is set to low state. Otherwise, it is set to high-impedance state.
+- `pin.out_value()` NOHEAP, optional - Return value stored in the output buffer of a pin, regardless of its mode.
+- `pin()` NOHEAP - Fast method to get the value of the pin. Fully equivalent to `Pin.value()`.
+- `pin(x)` NOHEAP - Fast method to set the value of the pin. Fully equivalent to `Pin.value(x)`.
+- `pin.toggle()` NOHEAP, optional - Toggle output value of a pin.
 
 **Getters and setters**
-- `pin.id()` NOHEAP; get only. - need to clarify what this really returns. I'm assuming a board ID.
+- `pin.id()` NOHEAP; get only. - Return ID of a pin. This MAY return `id` as specified in the constructor. Or it MAY return "normalized" software-specific pin ID.
 - `pin.mode([mode])` NOHEAP
 - `pin.pull([pull])` NOHEAP
 - `pin.drive([drive])` NOHEAP