[glib] key file: Clarify documentation around comments

[Matthias Clasen <matthiasc src gnome org>]

commit 6e576503876759d18c94bbad3c20ebb83b82c631
Author: Matthias Clasen <mclasen redhat com>
Date:   Tue Jun 16 18:38:27 2015 -0400

    key file: Clarify documentation around comments
    
    The documentation was not very clear about the handling
    of the '#' comment markers. State clearly how these are
    handled by the getter and the setter.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=479730

 glib/gkeyfile.c |   14 ++++++++++----
 1 files changed, 10 insertions(+), 4 deletions(-)
---
diff --git a/glib/gkeyfile.c b/glib/gkeyfile.c
index b1383b0..e168f56 100644
--- a/glib/gkeyfile.c
+++ b/glib/gkeyfile.c
@@ -3230,10 +3230,14 @@ g_key_file_set_top_comment (GKeyFile     *key_file,
  * @error: return location for a #GError
  *
  * Places a comment above @key from @group_name.
- * If @key is %NULL then @comment will be written above @group_name.  
- * If both @key and @group_name  are %NULL, then @comment will be 
+ *
+ * If @key is %NULL then @comment will be written above @group_name.
+ * If both @key and @group_name  are %NULL, then @comment will be
  * written above the first group in the file.
  *
+ * Note that this function prepends a '#' comment marker to
+ * each line of @comment.
+ *
  * Returns: %TRUE if the comment was written, %FALSE otherwise
  *
  * Since: 2.6
@@ -3456,10 +3460,12 @@ g_key_file_get_top_comment (GKeyFile  *key_file,
  * @error: return location for a #GError
  *
  * Retrieves a comment above @key from @group_name.
- * If @key is %NULL then @comment will be read from above 
- * @group_name. If both @key and @group_name are %NULL, then 
+ * If @key is %NULL then @comment will be read from above
+ * @group_name. If both @key and @group_name are %NULL, then
  * @comment will be read from above the first group in the file.
  *
+ * Note that the returned string includes the '#' comment markers.
+ *
  * Returns: a comment that should be freed with g_free()
  *
  * Since: 2.6