Start rewriting Pin section for clarity.

Hardware-API.md

@@ -117,14 +117,27 @@ def pin_handler(pin):
  
 ## The Pin class
 
-### Create and init a pin
+### Constructor
+
+Creates and initilizes a pin.
+
 `pin = Pin(id, mode, pull=Pin.PULL_NONE, *, value, drive, slew, alt, ...)`
-- `id`, and `mode` are mandatory and positional (`mode` can kw).
+- `id`: mandatory and positional. `id` can be an arbitrary object (among possible value types are: int (an internal Pin ID), str (a Pin name), tuple (pair of [port, pin]))
+- `mode`: is mandatory and positional (can be kw). Specifies pin mode:
+  - `Pin.IN` - Pin configured for input; there's additional requirement that, if viewed as output, pin was in high-impedance state. This requirement is almost universally satisfied by any MCU.
+  - `Pin.OUT` - Pin configured for (normal) output.
+  - `Pin.OPEN_DRAIN` - Pin configured for open-drain output, with special requirements for input handling. Open-drain output works in following way: if output value is set to 0, pin is low level; if output value is 1, pin is in high impedance state. Some MCUs don't support open-drain outputs directly, but it's almost always possible to emulate it (by outputting low level, in case of 0 value, or setting pin as input in case of 1 value). It is recommended that software implemented such emulation (see below for additional requirements for input handling).
+  - `Pin.ALT` - Pin is configured to perform alternative function, which is MCU-specific. For pin configured in such way, any other Pin methods (except .init()) are not applicable (calling them will lead to undefined, or hardware-specific, result)
+  - `Pin.ALT_OPEN_DRAIN` - Same as `Pin.ALT`, but pin is set as open-drain.
 - `pull` is optional and positional (also can be named).
 - The rest of args are kwonly.
-- Only `value` is required for a port to implement (initial value if given).
-- The rest are optional, and a port can define them and also define others.
-- `alt` specifies the alternate function, it is optional and the values it takes vary per port. Exists to allow advanced pin operations for ports that support it.
+- `value` is required for a software to implement; it is valid only for `Pin.OUT` and `Pin.OPEN_DRAIN` modes and specifies initial output pin value if given.
+- The rest are optional for software to implement, and a software can define them and also define others.
+- `alt` specifies an alternate function, it is optional and the values it takes vary per MCU. Exists to allow advanced pin operations for software that support it. This argument is valid only for `Pin.ALT` and `Pin.ALT_OPEN_DRAIN` modes. It may be used when a pin supports more than one alternate function. If only one pin alternate function is support for particular MCU, it is not required.
+
+### Pins with alternate function(s)
+
+As specified above, Pin class allows to set alternate function for particular pin, but does not specify any further operations on such pin (such pins are usually not used as GPIO, but driven by other hardware blocks in MCU). The only operation supported on such pin is re-initializing, by calling constructor or .init() method. If a pin with alternate function set is re-initialized with `Pin.IN`, `Pin.OUT`, or `Pin.OPEN_DRAIN`, the alternate function will be removed from such pin (it will be used as GPIO).
 
 ### Methods