diff --git a/USAGE.md b/USAGE.md
index a3bf94d20..df5d5bcb4 100644
--- a/USAGE.md
+++ b/USAGE.md
@@ -260,7 +260,8 @@ notcurses_term_dim_yx(const struct notcurses* n, int* restrict rows,
 // Refresh the physical screen to match what was last rendered (i.e., without
 // reflecting any changes since the last call to notcurses_render()). This is
 // primarily useful if the screen is externally corrupted, or if an
-// NCKEY_RESIZE event has been read and you're not ready to render.
+// NCKEY_RESIZE event has been read and you're not yet ready to render. The
+// current screen geometry is returned in 'y' and 'x', if they are not NULL.
 int notcurses_refresh(struct notcurses* n, int* restrict y, int* restrict x);
 
 // Enable or disable the terminal's cursor, if supported, placing it at
diff --git a/include/notcurses/notcurses.h b/include/notcurses/notcurses.h
index 969cf4f41..e1bf77f25 100644
--- a/include/notcurses/notcurses.h
+++ b/include/notcurses/notcurses.h
@@ -1075,7 +1075,8 @@ API int notcurses_linesigs_enable(struct notcurses* n);
 // Refresh the physical screen to match what was last rendered (i.e., without
 // reflecting any changes since the last call to notcurses_render()). This is
 // primarily useful if the screen is externally corrupted, or if an
-// NCKEY_RESIZE event has been read and you're not yet ready to render.
+// NCKEY_RESIZE event has been read and you're not yet ready to render. The
+// current screen geometry is returned in 'y' and 'x', if they are not NULL.
 API int notcurses_refresh(struct notcurses* n, int* RESTRICT y, int* RESTRICT x);
 
 // Extract the Notcurses context to which this plane is attached.