Add 'Initialisation options' to docs

docs/boards.md

@@ -27,11 +27,21 @@ Create an `LEDBoard` object by passing in a list of the LED pin numbers:
 leds = LEDBoard([2, 3, 4, 5, 6])
 ```
 
-### Methods
+#### Initialisation options
+
+```python
+LEDBoard(leds=None)
+```
+
+| Argument | Description | Values | Default |
+| -------- | ----------- | ------ | ------- |
+| `leds` | List of GPIO pins each LED is connected to, order preserved. | List | *Required* |
+
+#### Methods
 
 | Method | Description | Arguments |
 | ------ | ----------- | --------- |
-| `on()`     | Turn all the LEDs on. | None |
+| `on()`     | Turn all the LEDs on.  | None |
 | `off()`    | Turn all the LEDs off. | None |
 | `toggle()` | Toggle all the LEDs. For each LED, if it's on, turn it off; if it's off, turn it on. | None |
 | `blink()`  | Make the LEDs turn on and off repeatedly. | `on_time` - The amount of time (in seconds) for the LED to be on each iteration. Default: `1` |
@@ -39,7 +49,7 @@ leds = LEDBoard([2, 3, 4, 5, 6])
 |            |                                           | `n` - The number of iterations. `None` means infinite. Default: `None` |
 |            |                                           | `background` - If True, start a background thread to continue blinking and return immediately. If False, only return when the blink is finished (warning: the default value of n will result in this method never returning). Default: `True` |
 
-### Properties
+#### Properties
 
 | Property | Description | Type |
 | -------- | ----------- | ---- |
@@ -69,7 +79,19 @@ or just in order (red, amber, green):
 traffic = TrafficLights(2, 3, 4)
 ```
 
-### Methods
+#### Initialisation options
+
+```python
+TrafficLights(red=None, amber=None, green=None)
+```
+
+| Argument | Description | Values | Default |
+| -------- | ----------- | ------ | ------- |
+| `red`   | The GPIO pin number the red LED is connected to.   | Integer: `0` to `25` | *Required* |
+| `green` | The GPIO pin number the green LED is connected to. | Integer: `0` to `25` | *Required* |
+| `blue`  | The GPIO pin number the blue LED is connected to.  | Integer: `0` to `25` | *Required* |
+
+#### Methods
 
 | Method | Description | Arguments |
 | ------ | ----------- | --------- |
@@ -81,7 +103,7 @@ traffic = TrafficLights(2, 3, 4)
 |            |                                           | `n` - The number of iterations. `None` means infinite. Default: `None` |
 |            |                                           | `background` - If True, start a background thread to continue blinking and return immediately. If False, only return when the blink is finished (warning: the default value of n will result in this method never returning). Default: `True` |
 
-### Properties
+#### Properties
 
 | Property | Description | Type |
 | -------- | ----------- | ---- |
@@ -108,7 +130,11 @@ Create a `PiLiter` object:
 lite = PiLiter()
 ```
 
-### Methods
+#### Initialisation options
+
+None
+
+#### Methods
 
 | Method | Description | Arguments |
 | ------ | ----------- | --------- |
@@ -120,7 +146,7 @@ lite = PiLiter()
 |            |                                               | `n` - The number of iterations. `None` means infinite. Default: `None` |
 |            |                                               | `background` - If True, start a background thread to continue blinking and return immediately. If False, only return when the blink is finished (warning: the default value of n will result in this method never returning). Default: `True` |
 
-### Properties
+#### Properties
 
 | Property | Description | Type |
 | -------- | ----------- | ---- |
@@ -168,7 +194,11 @@ Create a `FishDish` object:
 fish = FishDish()
 ```
 
-### Methods
+#### Initialisation options
+
+None
+
+#### Methods
 
 | Method | Description | Arguments |
 | ------ | ----------- | --------- |
@@ -187,7 +217,7 @@ fish = FishDish()
 |                   |                                                   | `n` - The number of iterations. `None` means infinite. Default: `None` |
 |                   |                                                   | `background` - If True, start a background thread to continue blinking and return immediately. If False, only return when the blink is finished (warning: the default value of n will result in this method never returning). Default: `True` |
 
-### Properties
+#### Properties
 
 | Property | Description | Type |
 | -------- | ----------- | ---- |
@@ -238,7 +268,18 @@ pairs for each motor:
 robot = Robot(left=(4, 14), right=(17, 18))
 ```
 
-### Methods
+#### Initialisation options
+
+```python
+Robot(left=None, right=None))
+```
+
+| Argument | Description | Values | Default |
+| -------- | ----------- | ------ | ------- |
+| `left`  | The GPIO pins (forward and reverse) used by the left motor.  | Tuple | *Required* |
+| `right` | The GPIO pins (forward and reverse) used by the right motor. | Tuple | *Required* |
+
+#### Methods
 
 | Method | Description | Arguments |
 | ------ | ----------- | --------- |

docs/inputs.md

@@ -36,30 +36,34 @@ to:
 button = Button(2)
 ```
 
-The default behaviour is to set the *pull* state of the button to *up*. To
+#### Initialisation options
-change this behaviour, set the `pull_up` argument to `False` when creating your
-`Button` object.
 
 ```python
-button = Button(pin=2, pull_up=False)
+Button(pin=None, pull_up=True, bounce_time=None)
 ```
 
-### Methods
+| Argument | Description | Values | Default |
+| -------- | ----------- | ------ | ------- |
+| `pin`         | The GPIO pin number the button is connected to. | Integer: `0` to `25` | *Required* |
+| `pull_up`     | The pull state of the pin. `True` means pull up, `False` means pull down. | Boolean | `True` |
+| `bounce_time` | Specifies the length of time (in seconds) that the component will ignore changes in state after an initial change. | Integer or Float | `None` |
+
+#### Methods
 
 | Method | Description | Arguments |
 | ------ | ----------- | --------- |
 | `wait_for_press()`   | Halt the program until the button is pressed.  | `timeout` - The number of seconds to wait before proceeding if no event is detected. **Default: `None`** |
 | `wait_for_release()` | Halt the program until the button is released. | `timeout` - The number of seconds to wait before proceeding if no event is detected. **Default: `None`** |
 
-### Properties
+#### Properties
 
 | Property | Description | Type |
 | -------- | ----------- | ---- |
-| `pin`           | The GPIO pin number the button is connected to.                          | Integer          |
+| `pin`           | The GPIO pin number the button is connected to.                          | Integer            |
-| `is_pressed`    | The current state of the pin (`True` if pressed; otherwise `False`).     | Boolean          |
+| `is_pressed`    | The current state of the pin (`True` if pressed; otherwise `False`).     | Boolean            |
-| `pull_up`       | The pull state of the pin (`True` if pulled up; `False` if pulled down). | Boolean          |
+| `pull_up`       | The pull state of the pin (`True` if pulled up; `False` if pulled down). | Boolean            |
-| `when_pressed`  | A reference to the function to be called when the button is pressed.     | None or Function |
+| `when_pressed`  | A reference to the function to be called when the button is pressed.     | `None` or Function |
-| `when_released` | A reference to the function to be called when the button is released.    | None or Function |
+| `when_released` | A reference to the function to be called when the button is released.    | `None` or Function |
 
 ## Motion Sensor
 
@@ -87,21 +91,35 @@ connected to:
 pir = MotionSensor(4)
 ```
 
-### Methods
+#### Initialisation options
+
+```python
+MotionSensor(pin=None, queue_len=1, sample_rate=10, threshold=0.5, partial=False)
+```
+
+| Argument | Description | Values | Default |
+| -------- | ----------- | ------ | ------- |
+| `pin`         | The GPIO pin number the sensor is connected to. | Integer: `0` to `25` | *Required* |
+| `queue_len`   | ??? | Integer | `1` |
+| `sample_rate` | ??? | Integer | `10` |
+| `threshold`   | Proportion of sensor values required to determine motion state. | Float: `0` to `1` | `0.5` |
+| `partial`     | ??? | Boolean | `False` |
+
+#### Methods
 
 | Method | Description | Arguments |
 | ------ | ----------- | --------- |
 | `wait_for_motion()`    | Halt the program until motion is detected.    | `timeout` - The number of seconds to wait before proceeding if no motion is detected. **Default: `None`**    |
 | `wait_for_no_motion()` | Halt the program until no motion is detected. | `timeout` - The number of seconds to wait before proceeding if motion is still detected. **Default: `None`** |
 
-### Properties
+#### Properties
 
 | Property | Description | Type |
 | -------- | ----------- | ---- |
 | `pin`    | The GPIO pin number the sensor is connected to. | Integer |
 | `motion_detected` | The current state of the sensor (`True` if motion is detected; otherwise `False`). | Boolean |
-| `when_motion` | A reference to the function to be called when motion is detected. | None or Function |
+| `when_motion` | A reference to the function to be called when motion is detected. | `None` or Function |
-| `when_no_motion` | A reference to the function to be called when no motion is detected. | None or Function |
+| `when_no_motion` | A reference to the function to be called when no motion is detected. | `None` or Function |
 
 ## Light Sensor
 
@@ -126,21 +144,36 @@ connected to:
 light = LightSensor(4)
 ```
 
-### Methods
+#### Initialisation options
+
+```python
+LightSensor(pin=None, queue_len=5, charge_time_limit=10,
+    threshold=0.1, partial=False)
+```
+
+| Argument | Description | Values | Default |
+| -------- | ----------- | ------ | ------- |
+| `pin`         | The GPIO pin number the sensor is connected to. | Integer: `0` to `25` | *Required* |
+| `queue_len`   | ??? | Integer | `5` |
+| `charge_time_limit` | Maximum amount of time allowed to determine darkness. | Integer | `10` |
+| `threshold`   | Proportion of sensor values required to determine light level. | Float: `0` to `1` | `0.1` |
+| `partial`     | ??? | Boolean | `False` |
+
+#### Methods
 
 | Method | Description | Arguments |
 | ------ | ----------- | --------- |
 | `wait_for_light()` | Halt the program until light is detected.    | `timeout` - The number of seconds to wait before proceeding if light is not detected. **Default: `None`** |
 | `wait_for_dark()`  | Halt the program until darkness is detected. | `timeout` - The number of seconds to wait before proceeding if darkness is not detected. **Default: `None`** |
 
-### Properties
+#### Properties
 
 | Property | Description | Type |
 | -------- | ----------- | ---- |
-| `pin`            | The GPIO pin number the sensor is connected to.                       | Integer          |
+| `pin`            | The GPIO pin number the sensor is connected to.                       | Integer            |
-| `light_detected` | The current state of the sensor (`True` if light; otherwise `False`). | Boolean          |
+| `light_detected` | The current state of the sensor (`True` if light; otherwise `False`). | Boolean            |
-| `when_light`     | A reference to the function to be called when light is detected.      | None or Function |
+| `when_light`     | A reference to the function to be called when light is detected.      | `None` or Function |
-| `when_dark`      | A reference to the function to be called when darkness is detected.   | None or Function |
+| `when_dark`      | A reference to the function to be called when darkness is detected.   | `None` or Function |
 
 ## Temperature Sensor
 
@@ -164,11 +197,15 @@ Create a `TemperatureSensor` object:
 temp = TemperatureSensor()
 ```
 
-### Methods
+#### Initialisation options
 
 ...
 
-### Properties
+#### Methods
+
+...
+
+#### Properties
 
 | Property | Description | Type |
 | -------- | ----------- | ---- |
@@ -199,27 +236,40 @@ Create an `MCP3008` object:
 pot = MCP3008()
 ```
 
-Read the value of the device:
-
-```python
-print(pot.value)
-```
-
 Alternatively, access an input value with the `MCP3008`'s context manager:
 
 ```python
 with MCP3008() as pot:
-    print(pot.value)
+    # do something with pot
 ```
 
-It is possible to specify the `device` and the `channel` you wish to access.
+#### Initialisation options
-The previous example used the default value of `0` for each of these. To
-specify them, pass them in as arguments:
 
 ```python
-pot = MCP3008(device=1, channel=7)
+MCP3008(device=0, channel=0)
 ```
 
+| Argument | Description | Values | Default |
+| -------- | ----------- | ------ | ------- |
+| `device`  | Which of the two Chip Select SPI pins to access. | Integer: `0` or `1` | `0` |
+| `channel` | Which of the 8 ADC channels to access.           | Integer: `0` to `7` | `0` |
+
+#### Methods
+
+| Method | Description | Arguments |
+| ------ | ----------- | --------- |
+| `wait_for_light()` | Halt the program until light is detected.    | `timeout` - The number of seconds to wait before proceeding if light is not detected. **Default: `None`** |
+| `wait_for_dark()`  | Halt the program until darkness is detected. | `timeout` - The number of seconds to wait before proceeding if darkness is not detected. **Default: `None`** |
+
+#### Properties
+
+| Property | Description | Type |
+| -------- | ----------- | ---- |
+| `pin`            | The GPIO pin number the sensor is connected to.                       | Integer            |
+| `light_detected` | The current state of the sensor (`True` if light; otherwise `False`). | Boolean            |
+| `when_light`     | A reference to the function to be called when light is detected.      | `None` or Function |
+| `when_dark`      | A reference to the function to be called when darkness is detected.   | `None` or Function |
+
 ## MCP3004 Analogue-to-Digital Converter
 
 MCP3004 ADC (Analogue-to-Digital converter).
@@ -227,4 +277,5 @@ MCP3004 ADC (Analogue-to-Digital converter).
 The MCP3004 chip provides access to up to 4 analogue inputs, such as
 potentiometers, and read their values in digital form.
 
-The interface is identical to `MCP3008`.
+The interface is identical to `MCP3008`, except that only channels `0` to `3`
+are accessible.

docs/notes.md

@@ -155,11 +155,47 @@ which shows:
 gpiozero.Button
 ```
 
-Most classes in GPIO Zero require some parameters to create an object, for
+### Initialisation options
+
+Most classes in GPIO Zero require some arguments to create an object, for
 example the `LED` and `Button` examples require the pin number the device is
-attached to. Some classes require no parameters, others require multiple
+attached to:
-parameters, usually with some being optional. When parameters are optional,
+
-common default values are used.
+```python
+my_button = Button(2)
+```
+
+Some classes require no arguments due to the nature of the device:
+
+```python
+temp = TemperatureSensor()
+```
+
+Others have multiple arguments, usually with some being optional:
+
+```python
+temp = TemperatureSensor()
+```
+
+When arguments are optional, common default values are used.
+
+Arguments can be given unnamed, as long as they are in order:
+
+```python
+my_button = Button(2, False)
+```
+
+though this may be confusing, so named is better in this case:
+
+```python
+my_button = Button(pin=2, pull_up=False)
+```
+
+Alternatively, they can be given in any order, as long as they are named:
+
+```python
+my_button = Button(pin=2, bounce_time=0.5, pull_up=False)
+```
 
 ### Method
 
@@ -175,27 +211,32 @@ will call the `LED` class's `on()` function, relating to that instance of
 `LED`. If other `LED` objects have been created, they will not be affected by
 this action.
 
-In many cases, no parameters are required to call the method (like
+In many cases, no arguments are required to call the method (like
-`my_led.on()`). In other cases, optional parameters are available. For example:
+`my_led.on()`). In other cases, optional arguments are available. For example:
 
 ```python
 my_led.blink(2, 3)
 ```
 
-Here, the parameters `2` and `3` have been passed in as parameters. The `blink`
+Here, the arguments `2` and `3` have been passed in as arguments. The `blink`
 method allows configuration of `on_time` and `off_time`. This example means the
-LED will flash on for 2 seconds and stay off for 3.
+LED will flash on for 2 seconds and stay off for 3. This example may benefit
+from use of named arguments:
 
-Parameters can also be passed in by name, which means order is irrelevant. For
+```python
+my_led.blink(on_time=2, off_time=3)
+```
+
+arguments can also be passed in by name, which means order is irrelevant. For
 example:
 
 ```python
 my_led.blink(off_time=3)
 ```
 
-Here, only the `off_time` parameter has been provided, and all other parameters
+Here, only the `off_time` argument has been provided, and all other arguments
 will use their default values. Methods in GPIO Zero use sensible common default
-values, but are configurable.
+values, but are configurable when necessary.
 
 ### Property
 

docs/outputs.md

@@ -36,7 +36,18 @@ Create an `LED` object by passing in the pin number the LED is connected to:
 led = LED(17)
 ```
 
-### Methods
+#### Initialisation options
+
+```python
+LED(pin=None, active_high=True)
+```
+
+| Argument | Description | Values | Default |
+| -------- | ----------- | ------ | ------- |
+| `pin` | The GPIO pin number the LED is connected to. | Integer: `0` to `25` | *Required* |
+| `active_high` | Whether high or low voltage turns the LED on. | Boolean | `True` |
+
+#### Methods
 
 | Method | Description | Arguments |
 | ------ | ----------- | --------- |
@@ -48,7 +59,7 @@ led = LED(17)
 |            |                                          | `n` - The number of iterations. `None` means infinite. **Default: `None`** |
 |            |                                          | `background` - If `True`, start a background thread to continue blinking and return immediately. If `False`, only return when the blink is finished (warning: the default value of n will result in this method never returning). **Default: `True`** |
 
-### Properties
+#### Properties
 
 | Property | Description | Type |
 | -------- | ----------- | ---- |
@@ -81,7 +92,18 @@ to:
 buzzer = Buzzer(3)
 ```
 
-### Methods
+#### Initialisation options
+
+```python
+Buzzer(pin=None, active_high=True)
+```
+
+| Argument | Description | Values | Default |
+| -------- | ----------- | ------ | ------- |
+| `pin`         | The GPIO pin number the buzzer is connected to.  | Integer: `0` to `25` | *Required* |
+| `active_high` | Whether high or low voltage turns the buzzer on. | Boolean              | `True` |
+
+#### Methods
 
 | Method | Description | Arguments |
 | ------ | ----------- | --------- |
@@ -93,7 +115,7 @@ buzzer = Buzzer(3)
 |            |                                          | `n` - The number of iterations. `None` means infinite. **Default: `None`** |
 |            |                                          | `background` - If `True`, start a background thread to continue blinking and return immediately. If `False`, only return when the blink is finished (warning: the default value of n will result in this method never returning). **Default: `True`** |
 
-### Properties
+#### Properties
 
 | Property | Description | Type |
 | -------- | ----------- | ---- |
@@ -132,7 +154,19 @@ or just in order (red, green, blue):
 led = RGBLED(2, 3, 4)
 ```
 
-### Methods
+#### Initialisation options
+
+```python
+RGBLED(red=None, green=None, blue=None)
+```
+
+| Argument | Description | Values | Default |
+| -------- | ----------- | ------ | ------- |
+| `red`   | The GPIO pin number the red LED is connected to.   | Integer: `0` to `25` | *Required* |
+| `green` | The GPIO pin number the green LED is connected to. | Integer: `0` to `25` | *Required* |
+| `blue`  | The GPIO pin number the blue LED is connected to.  | Integer: `0` to `25` | *Required* |
+
+#### Methods
 
 | Method | Description | Arguments |
 | ------ | ----------- | --------- |
@@ -144,13 +178,13 @@ led = RGBLED(2, 3, 4)
 |            |                                          | `n` - The number of iterations. `None` means infinite. **Default: `None`** |
 |            |                                          | `background` - If `True`, start a background thread to continue blinking and return immediately. If `False`, only return when the blink is finished (warning: the default value of n will result in this method never returning). **Default: `True`** |
 
-### Properties
+#### Properties
 
 | Property | Description | Type |
 | -------- | ----------- | ---- |
-| `red`   | The brightness value of the red LED (`0` to `1`).   | Integer or Float |
+| `red`   | The brightness value of the red LED (`0` to `1`).                   | Integer or Float |
-| `green` | The brightness value of the green LED (`0` to `1`). | Integer or Float |
+| `green` | The brightness value of the green LED (`0` to `1`).                 | Integer or Float |
-| `blue`  | The brightness value of the blue LED (`0` to `1`).  | Integer or Float |
+| `blue`  | The brightness value of the blue LED (`0` to `1`).                  | Integer or Float |
 | `color` | The brightness values of the three LEDs `(0, 0, 0)` to `(1, 1, 1)`. | Tuple |
 
 ## Motor
@@ -178,7 +212,18 @@ Create a `Motor` object by passing in the pin numbers the motor is connected to:
 motor = Motor(forward=17, back=18)
 ```
 
-### Methods
+#### Initialisation options
+
+```python
+Motor(forward=None, back=None)
+```
+
+| Argument | Description | Values | Default |
+| -------- | ----------- | ------ | ------- |
+| `forward` | The GPIO pin number the forward gear of the motor is connected to. | Integer: `0` to `25` | *Required* |
+| `back`    | The GPIO pin number the reverse gear of the motor is connected to. | Integer: `0` to `25` | *Required* |
+
+#### Methods
 
 | Method | Description | Arguments |
 | ------ | ----------- | --------- |