diff --git a/shared-bindings/displayio/Display.c b/shared-bindings/displayio/Display.c
index b5c8868de5..96ce284efa 100644
--- a/shared-bindings/displayio/Display.c
+++ b/shared-bindings/displayio/Display.c
@@ -230,22 +230,23 @@ STATIC mp_obj_t displayio_display_obj_show(mp_obj_t self_in, mp_obj_t group_in)
 MP_DEFINE_CONST_FUN_OBJ_2(displayio_display_show_obj, displayio_display_obj_show);
 
 //|     def refresh(self, *, target_frames_per_second: Optional[int] = None, minimum_frames_per_second: int = 0) -> bool:
-//|         """When auto refresh is off, waits for the target frame rate and then refreshes the display,
-//|         returning True. If the call has taken too long since the last refresh call for the given
-//|         target frame rate, then the refresh returns False immediately without updating the screen to
+//|         """When auto_refresh is off, and :py:attr:`target_frames_per_second` is not `None` this waits
+//|         for the target frame rate and then refreshes the display,
+//|         returning `True`. If the call has taken too long since the last refresh call for the given
+//|         target frame rate, then the refresh returns `False` immediately without updating the screen to
 //|         hopefully help getting caught up.
 //|
 //|         If the time since the last successful refresh is below the minimum frame rate, then an
-//|         exception will be raised. The default ``minimum_frames_per_second`` of 0 disables this behavior.
+//|         exception will be raised. The default :py:attr:`minimum_frames_per_second` of 0 disables this behavior.
 //|
-//|         When auto refresh is off, ``display.refresh()`` or ``display.refresh(target_frames_per_second=None)``
+//|         When auto_refresh is off, and :py:attr:`target_frames_per_second` is `None` this
 //|         will update the display immediately.
 //|
-//|         When auto refresh is on, updates the display immediately. (The display will also update
+//|         When auto_refresh is on, updates the display immediately. (The display will also update
 //|         without calls to this.)
 //|
-//|         :param int target_frames_per_second: How many times a second `refresh` should be called and the screen updated.
-//|             Set to `None` for immediate refresh.
+//|         :param Optional[int] target_frames_per_second: The target frame rate that :py:func:`refresh` should try to
+//|             achieve. Set to `None` for immediate refresh.
 //|         :param int minimum_frames_per_second: The minimum number of times the screen should be updated per second."""
 //|         ...
 //|