-/* MAKES A COPY OF THE KEY!!! */
-gboolean split_string_from_file_on_equals ( gchar *buf, gchar **key, gchar **val )
+/**
+ * split_string_from_file_on_equals:
+ *
+ * @buf: the input string
+ * @key: newly allocated string that is before the '='
+ * @val: newly allocated string after the '='
+ *
+ * Designed for file line processing, so it ignores strings beginning with special
+ * characters, such as '#'; returns false in such situations.
+ * Also returns false if no equals character is found
+ *
+ * e.g. if buf = "GPS.parameter=42"
+ * key = "GPS.parameter"
+ * val = "42"
+ */
+gboolean split_string_from_file_on_equals ( const gchar *buf, gchar **key, gchar **val )