Expand docs

docs/inputs.md

@@ -38,8 +38,8 @@ button = Button(pin=2, pull_up=False)
 
 | Method | Description | Arguments |
 | ------ | ----------- | --------- |
-| `wait_for_press()` | Halt the program until the button is pressed. | `timeout=None` |
+| `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=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
 

docs/notes.md

@@ -1,6 +1,6 @@
 # Notes
 
-1. BCM pin numbering
+1. **BCM pin numbering**
 
     This library uses BCM pin numbering for the GPIO pins, as opposed to BOARD. Unlike the `RPi.GPIO` library, it is not configurable.
 
@@ -36,6 +36,48 @@
     - *5V = 5 Volts*
     - *DNC = Do not connect (special use pins)*
 
-1. Wiring
+1. **Wiring**
 
     All components must be wired up correctly before using with this library.
+
+1. **Keep your program alive with `signal.pause`**
+
+    The following program looks like it should turn an LED on:
+
+    ```python
+    from gpiozero import led
+
+    led = LED(2)
+
+    led.on()
+    ```
+
+    And it does, if you're using the Python shell, IPython shell or IDLE shell, but if you saved this program as a Python file and ran it, it would flash on for a moment then the program would end and it would turn off.
+
+    The following file includes an intentional `pause` to keep the program alive:
+
+    ```python
+    from gpiozero import LED
+    from signal import pause
+
+    led = LED(2)
+
+    led.on()
+
+    pause()
+    ```
+
+    Now running the program will stay running, leaving the LED on, until it is forced to quit.
+
+    Similarly, when setting up callbacks on button presses or other input devices, the program needs to be running for the events to be detected:
+
+    ```python
+    from gpiozero import Button
+    from signal import pause
+
+    button = Button(2)
+
+    button.when_pressed = lambda: print("Button was pressed!")
+
+    pause()
+    ```

docs/outputs.md

@@ -35,7 +35,10 @@ led = LED(2)
 | `on()` | Turn the LED on. | None |
 | `off()` | Turn the LED off. | None |
 | `toggle()` | Toggle the LED. If it's on, turn it off; if it's off, turn it on. | None |
-| `blink()` | Make the LED turn on and off repeatedly. | `on_time=1`, `off_time=1`, `n=1`, `background=True` |
+| `blink()` | Make the LED turn on and off repeatedly. | `on_time` - The amount of time (in seconds) for the LED to be on each iteration. Default: `1` |
+|           |                                          | `off_time` - The amount of time (in seconds) for the LED to be off each iteration. Default: `1` |
+|           |                                          | `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
 
@@ -73,7 +76,10 @@ buzzer = Buzzer(3)
 | `on()` | Turn the buzzer on. | None |
 | `off()` | Turn the buzzer off. | None |
 | `toggle()` | Toggle the buzzer. If it's on, turn it off; if it's off, turn it on. | None |
-| `blink()` | Make the buzzer turn on and off repeatedly. | `on_time=1`, `off_time=1`, `n=1`, `background=True` |
+| `blink()` | Make the LED turn on and off repeatedly. | `on_time` - The amount of time (in seconds) for the LED to be on each iteration. Default: `1` |
+|           |                                          | `off_time` - The amount of time (in seconds) for the LED to be off each iteration. Default: `1` |
+|           |                                          | `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
 
@@ -116,6 +122,7 @@ led = RGBLED(2, 3, 4)
 | ------ | ----------- | --------- |
 | `on()` | Turn all the LEDs on (makes white light). | None |
 | `off()` | Turn all the LEDs off. | None |
+| `toggle()` | Toggle the LED. If it's on (at all), turn it off; if it's off, turn it on. | None |
 
 ### Properties
 

docs/recipes.md

@@ -1,5 +1,7 @@
 # Recipes
 
+*Note that reaching the end of a Python file will terminate the process and GPIOs may be reset. Keep your program alive with `signal.pause` - see the [notes](notes.md) page for more information.*
+
 ## LED
 
 Turn an LED on and off repeatedly: