[Gnucash-changes] Document the weird gnc_extract_directory function very clearly.

[Christian Stimming]

Log Message:
-----------
Document the weird gnc_extract_directory function very clearly.

Tags:
----
gnucash-gnome2-dev

Modified Files:
--------------
    gnucash/src/app-utils:
        gnc-ui-util.h

Revision Data
-------------
Index: gnc-ui-util.h
===================================================================
RCS file: /home/cvs/cvsroot/gnucash/src/app-utils/gnc-ui-util.h,v
retrieving revision 1.22.2.10
retrieving revision 1.22.2.11
diff -Lsrc/app-utils/gnc-ui-util.h -Lsrc/app-utils/gnc-ui-util.h -u -r1.22.2.10 -r1.22.2.11
--- src/app-utils/gnc-ui-util.h
+++ src/app-utils/gnc-ui-util.h
@@ -57,6 +57,22 @@
 /* Default directories **********************************************/
 
 void gnc_init_default_directory (char **dirname);
+/** 
+ * Extracts the directory part of the given 'filename' into the char
+ * pointer variable '*dirname'. If the 'filename' is NULL or does not
+ * contain any directory separator '/', then '*dirname' will be set to
+ * NULL.
+ * 
+ * WATCH OUT: If '*dirname' (i.e. the underlying char pointer
+ * variable) is non-NULL, then it will be free()'d. Make sure that you
+ * have initialized it to NULL, or otherwise you will get a bogus
+ * free() or a double-free() here. FIXME: This is probably not-so-good
+ * behaviour and should be changed (2005-10-08, cstim).
+ *
+ * Again watch out: The caller takes ownership of the char buffer
+ * '*dirname', i.e. the caller has to do a g_free(*dirname) when that
+ * buffer is no longer in use.
+*/
 void gnc_extract_directory (char **dirname, const char *filename);