gpollable: Clarify that can_poll() must be called before other methods

Both `GPollableInputStream` and `GPollableOutputStream` are dynamic
interfaces, in that their implementation on a class may only be
functional if certain prerequisites are met at runtime. For example,
a `GConverterInputStream` is only pollable if its base stream is
pollable, and that’s determined at runtime rather than compile time.

As such, both interfaces have a `can_poll()` method. If that method
returns `FALSE`, the behaviour of all other methods on the interface is
undefined.

That was mentioned in the documentation for `can_poll()`, but not any of
the other documentation for the interfaces, which made it a bit hard to
find.

Mention it more widely.

Signed-off-by: Philip Withnall <pwithnall@endlessos.org>

Fixes: #2952

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).

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