[gtksourceview/wip/file-loader-set-modified] FileLoader: document not_undoable_action() and set_modified() behavior

[Sébastien Wilmet <swilmet src gnome org>]

commit 9332104316383a608c9260aee172758df270eac6
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Sat Jun 20 11:39:44 2015 +0200

    FileLoader: document not_undoable_action() and set_modified() behavior
    
    Since apps rely on that, it's better to document it.

 gtksourceview/gtksourcefileloader.c |   12 ++++++++++++
 1 files changed, 12 insertions(+), 0 deletions(-)
---
diff --git a/gtksourceview/gtksourcefileloader.c b/gtksourceview/gtksourcefileloader.c
index d8b8b8e..c0fa6fa 100644
--- a/gtksourceview/gtksourcefileloader.c
+++ b/gtksourceview/gtksourcefileloader.c
@@ -43,6 +43,18 @@
  * A file loader should be used only for one load operation, including errors
  * handling. If an error occurs, you can reconfigure the loader and relaunch the
  * operation with gtk_source_file_loader_load_async().
+ *
+ * Running a #GtkSourceFileLoader is an undoable action for the
+ * #GtkSourceBuffer. That is, gtk_source_buffer_begin_not_undoable_action() and
+ * gtk_source_buffer_end_not_undoable_action() are called, which delete the
+ * undo/redo history.
+ *
+ * After a file loading, the buffer is reset to the contents provided by the
+ * #GFile or #GInputStream, so the buffer is set as “unmodified”, that is,
+ * gtk_text_buffer_set_modified() is called with %FALSE. If the contents isn't
+ * saved somewhere (for example if you load from stdin), then you should
+ * probably call gtk_text_buffer_set_modified() with %TRUE after calling
+ * gtk_source_file_loader_load_finish().
  */
 
 #if 0