[glib] GSeekable: improve g_seekable_[can_]truncate docs

[Philip Withnall <pwithnall src gnome org>]

commit 41112ef00ddbf85ff377ddc330dd7ab28034259d
Author: Will Thompson <wjt endlessm com>
Date:   Wed Nov 1 14:41:00 2017 +0000

    GSeekable: improve g_seekable_[can_]truncate docs
    
    I was not born next to a PDP-11, either, but I think this is marginally more informative!
    
    https://bugzilla.gnome.org/show_bug.cgi?id=573251

 gio/gseekable.c |   10 ++++++----
 1 files changed, 6 insertions(+), 4 deletions(-)
---
diff --git a/gio/gseekable.c b/gio/gseekable.c
index 26159d0..5b44602 100644
--- a/gio/gseekable.c
+++ b/gio/gseekable.c
@@ -141,7 +141,8 @@ g_seekable_seek (GSeekable     *seekable,
  * g_seekable_can_truncate:
  * @seekable: a #GSeekable.
  * 
- * Tests if the stream can be truncated.
+ * Tests if the length of the stream can be adjusted with
+ * g_seekable_truncate().
  * 
  * Returns: %TRUE if the stream can be truncated, %FALSE otherwise.
  **/
@@ -160,12 +161,14 @@ g_seekable_can_truncate (GSeekable *seekable)
 /**
  * g_seekable_truncate:
  * @seekable: a #GSeekable.
- * @offset: a #goffset.
+ * @offset: new length for @seekable, in bytes.
  * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. 
  * @error: a #GError location to store the error occurring, or %NULL to 
  * ignore.
  * 
- * Truncates a stream with a given #offset. 
+ * Sets the length of the stream to @offset. If the stream was previously
+ * larger than @offset, the extra data is discarded. If the stream was
+ * previouly shorter than @offset, it is extended with NUL ('\0') bytes.
  * 
  * If @cancellable is not %NULL, then the operation can be cancelled by
  * triggering the cancellable object from another thread. If the operation
@@ -173,7 +176,6 @@ g_seekable_can_truncate (GSeekable *seekable)
  * operation was partially finished when the operation was cancelled the
  * partial result will be returned, without an error.
  *
- * Virtual: truncate_fn
  * Returns: %TRUE if successful. If an error
  *     has occurred, this function will return %FALSE and set @error
  *     appropriately if present.