Merge pull request adafruit#7659 from dhalbert/gifio-displayio-doc

dhalbert · web-flow · commit cb6201d952c7 · 2023-02-28T15:57:29.000-05:00
Update gifio and displayio documentation
diff --git a/shared-bindings/displayio/Display.c b/shared-bindings/displayio/Display.c
@@ -240,10 +240,16 @@ static displayio_display_obj_t *native_display(mp_obj_t display_obj) {
 }
 
 //|     def show(self, group: Group) -> None:
-//|         """Switches to displaying the given group of layers. When group is None, the default
+//|         """
+//|         .. note:: `show()` is deprecated and will be removed in CircuitPython 9.0.0.
+//|           Use ``.root_group = group`` instead.
+//|
+//|         Switches to displaying the given group of layers. When group is None, the default
 //|         CircuitPython terminal will be shown.
 //|
-//|         :param Group group: The group to show."""
+//|         :param Group group: The group to show.
+//|
+//|         """
 //|         ...
 STATIC mp_obj_t displayio_display_obj_show(mp_obj_t self_in, mp_obj_t group_in) {
     displayio_display_obj_t *self = native_display(self_in);
@@ -419,7 +425,9 @@ MP_PROPERTY_GETTER(displayio_display_bus_obj,
     (mp_obj_t)&displayio_display_get_bus_obj);
 
 //|     root_group: Group
-//|     """The root group on the display."""
+//|     """The root group on the display.
+//|     If the root group is set to ``None``, the default CircuitPython terminal will be shown.
+//|     """
 STATIC mp_obj_t displayio_display_obj_get_root_group(mp_obj_t self_in) {
     displayio_display_obj_t *self = native_display(self_in);
     return common_hal_displayio_display_get_root_group(self);
diff --git a/shared-bindings/displayio/EPaperDisplay.c b/shared-bindings/displayio/EPaperDisplay.c
@@ -242,7 +242,11 @@ static displayio_epaperdisplay_obj_t *native_display(mp_obj_t display_obj) {
 }
 
 //|     def show(self, group: Group) -> None:
-//|         """Switches to displaying the given group of layers. When group is None, the default
+//|         """
+//|         .. note:: `show()` is deprecated and will be removed in CircuitPython 9.0.0.
+//|           Use ``.root_group = group`` instead.
+//|
+//|         Switches to displaying the given group of layers. When group is None, the default
 //|         CircuitPython terminal will be shown.
 //|
 //|         :param Group group: The group to show."""
@@ -379,7 +383,9 @@ MP_PROPERTY_GETTER(displayio_epaperdisplay_bus_obj,
     (mp_obj_t)&displayio_epaperdisplay_get_bus_obj);
 
 //|     root_group: Group
-//|     """The root group on the epaper display."""
+//|     """The root group on the epaper display.
+//|     If the root group is set to ``None``, the default CircuitPython terminal will be shown.
+//|     """
 //|
 STATIC mp_obj_t displayio_epaperdisplay_obj_get_root_group(mp_obj_t self_in) {
     displayio_epaperdisplay_obj_t *self = native_display(self_in);
diff --git a/shared-bindings/gifio/OnDiskGif.c b/shared-bindings/gifio/OnDiskGif.c
@@ -48,22 +48,35 @@
 //|       display.root_group = splash
 //|
 //|       odg = gifio.OnDiskGif('/sample.gif')
+//|
+//|       start = time.monotonic()
 //|       odg.next_frame() # Load the first frame
-//|       # Depending on your display the next line may need Colorspace.RGB565 instead of Colorspace.RGB565_SWAPPED
-//|       face = displayio.TileGrid(odg.bitmap, pixel_shader=displayio.ColorConverter(input_colorspace=displayio.Colorspace.RGB565_SWAPPED))
+//|       end = time.monotonic()
+//|       overhead = end - start
+//|
+//|       face = displayio.TileGrid(
+//|           odg.bitmap,
+//|           pixel_shader=displayio.ColorConverter(
+//|               input_colorspace=displayio.Colorspace.RGB565_SWAPPED
+//|           ),
+//|       )
 //|       splash.append(face)
 //|       board.DISPLAY.refresh()
 //|
-//|       # Wait forever
+//|       # Display repeatedly.
 //|       while True:
+//|           # Sleep for the frame delay specified by the GIF,
+//|           # minus the overhead measured to advance between frames.
+//|           time.sleep(max(0, next_delay - overhead))
 //|           next_delay = odg.next_frame()
-//|           time.sleep(next_delay)"""
+//|     """
 //|
 //|     def __init__(self, file: str) -> None:
-//|         """Create an OnDiskGif object with the given file.
+//|         """Create an `OnDiskGif` object with the given file.
+//|         The GIF frames are decoded into RGB565 big-endian format.
+//|         `displayio` expects little-endian, so the example above uses `Colorspace.RGB565_SWAPPED`.
 //|
 //|         :param file file: The name of the GIF file.
-//|
 //|         """
 //|         ...
 STATIC mp_obj_t gifio_ondiskgif_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *all_args) {
