diff --git a/gio/gpollableinputstream.c b/gio/gpollableinputstream.c
index ac8ac492b..3f76cb6d4 100644
--- a/gio/gpollableinputstream.c
+++ b/gio/gpollableinputstream.c
@@ -37,6 +37,11 @@
  * interfacing with a non-GIO API that expects
  * UNIX-file-descriptor-style asynchronous I/O rather than GIO-style.
  *
+ * Some classes may implement #GPollableInputStream but have only certain
+ * instances of that class be pollable. If g_pollable_input_stream_can_poll()
+ * returns %FALSE, then the behavior of other #GPollableInputStream methods is
+ * undefined.
+ *
  * Since: 2.28
  */
 
@@ -98,6 +103,9 @@ g_pollable_input_stream_can_poll (GPollableInputStream *stream)
  * g_pollable_input_stream_read_nonblocking(), which will return a
  * %G_IO_ERROR_WOULD_BLOCK error rather than blocking.
  *
+ * The behaviour of this method is undefined if
+ * g_pollable_input_stream_can_poll() returns %FALSE for @stream.
+ *
  * Returns: %TRUE if @stream is readable, %FALSE if not. If an error
  *   has occurred on @stream, this will result in
  *   g_pollable_input_stream_is_readable() returning %TRUE, and the
@@ -127,6 +135,9 @@ g_pollable_input_stream_is_readable (GPollableInputStream *stream)
  * triggers, so you should use g_pollable_input_stream_read_nonblocking()
  * rather than g_input_stream_read() from the callback.
  *
+ * The behaviour of this method is undefined if
+ * g_pollable_input_stream_can_poll() returns %FALSE for @stream.
+ *
  * Returns: (transfer full): a new #GSource
  *
  * Since: 2.28
@@ -179,6 +190,9 @@ g_pollable_input_stream_default_read_nonblocking (GPollableInputStream  *stream,
  * may happen if you call this method after a source triggers due
  * to having been cancelled.
  *
+ * The behaviour of this method is undefined if
+ * g_pollable_input_stream_can_poll() returns %FALSE for @stream.
+ *
  * Virtual: read_nonblocking
  * Returns: the number of bytes read, or -1 on error (including
  *   %G_IO_ERROR_WOULD_BLOCK).
diff --git a/gio/gpollableoutputstream.c b/gio/gpollableoutputstream.c
index fd9860d6e..f33267aa1 100644
--- a/gio/gpollableoutputstream.c
+++ b/gio/gpollableoutputstream.c
@@ -38,6 +38,11 @@
  * interfacing with a non-GIO API that expects
  * UNIX-file-descriptor-style asynchronous I/O rather than GIO-style.
  *
+ * Some classes may implement #GPollableOutputStream but have only certain
+ * instances of that class be pollable. If g_pollable_output_stream_can_poll()
+ * returns %FALSE, then the behavior of other #GPollableOutputStream methods is
+ * undefined.
+ *
  * Since: 2.28
  */
 
@@ -105,6 +110,9 @@ g_pollable_output_stream_can_poll (GPollableOutputStream *stream)
  * g_pollable_output_stream_write_nonblocking(), which will return a
  * %G_IO_ERROR_WOULD_BLOCK error rather than blocking.
  *
+ * The behaviour of this method is undefined if
+ * g_pollable_output_stream_can_poll() returns %FALSE for @stream.
+ *
  * Returns: %TRUE if @stream is writable, %FALSE if not. If an error
  *   has occurred on @stream, this will result in
  *   g_pollable_output_stream_is_writable() returning %TRUE, and the
@@ -134,6 +142,9 @@ g_pollable_output_stream_is_writable (GPollableOutputStream *stream)
  * triggers, so you should use g_pollable_output_stream_write_nonblocking()
  * rather than g_output_stream_write() from the callback.
  *
+ * The behaviour of this method is undefined if
+ * g_pollable_output_stream_can_poll() returns %FALSE for @stream.
+ *
  * Returns: (transfer full): a new #GSource
  *
  * Since: 2.28
@@ -251,6 +262,9 @@ g_pollable_output_stream_default_writev_nonblocking (GPollableOutputStream  *str
  * transports like D/TLS require that you re-send the same @buffer and
  * @count in the next write call.
  *
+ * The behaviour of this method is undefined if
+ * g_pollable_output_stream_can_poll() returns %FALSE for @stream.
+ *
  * Virtual: write_nonblocking
  * Returns: the number of bytes written, or -1 on error (including
  *   %G_IO_ERROR_WOULD_BLOCK).
@@ -319,6 +333,9 @@ g_pollable_output_stream_write_nonblocking (GPollableOutputStream  *stream,
  * transports like D/TLS require that you re-send the same @vectors and
  * @n_vectors in the next write call.
  *
+ * The behaviour of this method is undefined if
+ * g_pollable_output_stream_can_poll() returns %FALSE for @stream.
+ *
  * Virtual: writev_nonblocking
  *
  * Returns: %@G_POLLABLE_RETURN_OK on success, %G_POLLABLE_RETURN_WOULD_BLOCK