From afbf59019eec003ed79ee4467d0f3f76c00c68d2 Mon Sep 17 00:00:00 2001
From: Scott Shawcroft <scott@tannewt.org>
Date: Tue, 12 Mar 2019 16:20:12 -0700
Subject: [PATCH] Update displayio docs to add detail to display bus comments

Fixes #1599
---
 shared-bindings/displayio/FourWire.c    |  9 +++++++--
 shared-bindings/displayio/ParallelBus.c | 14 ++++++++++----
 shared-bindings/displayio/__init__.c    |  5 +++--
 3 files changed, 20 insertions(+), 8 deletions(-)

diff --git a/shared-bindings/displayio/FourWire.c b/shared-bindings/displayio/FourWire.c
index 70cd427471..8ffe54be09 100644
--- a/shared-bindings/displayio/FourWire.c
+++ b/shared-bindings/displayio/FourWire.c
@@ -46,14 +46,19 @@
 //| Manage updating a display over SPI four wire protocol in the background while Python code runs.
 //| It doesn't handle display initialization.
 //|
-//| .. class:: FourWire(spi_bus, *, command, chip_select, reset)
+//| .. class:: FourWire(spi_bus, *, command, chip_select, reset=None)
 //|
 //|   Create a FourWire object associated with the given pins.
 //|
+//|   The SPI bus and pins are then in use by the display until `displayio.release_displays()` is
+//|   called even after a reload. (It does this so CircuitPython can use the display after your code
+//|   is done.) So, the first time you initialize a display bus in code.py you should call
+//|   :py:func`displayio.release_displays` first, otherwise it will error after the first code.py run.
+//|
 //|   :param busio.SPI spi_bus: The SPI bus that make up the clock and data lines
 //|   :param microcontroller.Pin command: Data or command pin
 //|   :param microcontroller.Pin chip_select: Chip select pin
-//|   :param microcontroller.Pin reset: Reset pin
+//|   :param microcontroller.Pin reset: Reset pin. When None only software reset can be used
 //|
 STATIC mp_obj_t displayio_fourwire_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
     enum { ARG_spi_bus, ARG_command, ARG_chip_select, ARG_reset };
diff --git a/shared-bindings/displayio/ParallelBus.c b/shared-bindings/displayio/ParallelBus.c
index 6a499ed069..00a96d2301 100644
--- a/shared-bindings/displayio/ParallelBus.c
+++ b/shared-bindings/displayio/ParallelBus.c
@@ -39,18 +39,24 @@
 
 //| .. currentmodule:: displayio
 //|
-//| :class:`ParallelBus` -- Manage updating a display over SPI four wire protocol
+//| :class:`ParallelBus` -- Manage updating a display over 8-bit parallel bus
 //| ==============================================================================
 //|
-//| Manage updating a display over SPI four wire protocol in the background while Python code runs.
-//| It doesn't handle display initialization.
+//| Manage updating a display over 8-bit parallel bus in the background while Python code runs. This
+//| protocol may be refered to as 8080-I Series Parallel Interface in datasheets. It doesn't handle
+//| display initialization.
 //|
 //| .. class:: ParallelBus(*, data0, command, chip_select, write, read, reset)
 //|
 //|   Create a ParallelBus object associated with the given pins. The bus is inferred from data0
 //|   by implying the next 7 additional pins on a given GPIO port.
 //|
-//|   :param microcontroller.Pin: The first data pin. The rest are implied
+//|   The parallel bus and pins are then in use by the display until `displayio.release_displays()`
+//|   is called even after a reload. (It does this so CircuitPython can use the display after your
+//|   code is done.) So, the first time you initialize a display bus in code.py you should call
+//|   :py:func`displayio.release_displays` first, otherwise it will error after the first code.py run.
+//|
+//|   :param microcontroller.Pin data0: The first data pin. The rest are implied
 //|   :param microcontroller.Pin command: Data or command pin
 //|   :param microcontroller.Pin chip_select: Chip select pin
 //|   :param microcontroller.Pin write: Write pin
diff --git a/shared-bindings/displayio/__init__.c b/shared-bindings/displayio/__init__.c
index 1ee7550140..177bd5fff1 100644
--- a/shared-bindings/displayio/__init__.c
+++ b/shared-bindings/displayio/__init__.c
@@ -71,8 +71,6 @@
 //|     Shape
 //|     TileGrid
 //|
-//| All libraries change hardware state but are never deinit
-//|
 
 
 //| .. method:: release_displays()
@@ -81,6 +79,9 @@
 //|   release the builtin display on boards that have one. You will need to reinitialize it yourself
 //|   afterwards.
 //|
+//|   Use this once in your code.py if you initialize a display. Place it right before the
+//|   initialization so the display is active as long as possible.
+//|
 STATIC mp_obj_t displayio_release_displays(void) {
     common_hal_displayio_release_displays();
     return mp_const_none;