From 13950b2fa2809046453363098014b144d384248d Mon Sep 17 00:00:00 2001
From: Nick Bowler <nbowler@draconx.ca>
Date: Fri, 24 Jul 2009 12:10:57 -0400
Subject: [PATCH] uobject: Add some descriptions of the loadable/exportable
 interfaces.

---
 src/uobject/exportable.h | 16 ++++++++++++++++
 src/uobject/loadable.h   |  6 ++++++
 2 files changed, 22 insertions(+)

diff --git a/src/uobject/exportable.h b/src/uobject/exportable.h
index 931d5b9..6aa58b3 100644
--- a/src/uobject/exportable.h
+++ b/src/uobject/exportable.h
@@ -33,6 +33,10 @@
 
 typedef struct UObjectExportable UObjectExportable;
 
+/*
+ * Interface for UObjects that support exporting to a file.  For example, a
+ * texture might be saved to disk as a PNG image for editing.
+ */
 struct UObjectExportable {
 	GTypeInterface parent;
 
@@ -42,7 +46,19 @@ struct UObjectExportable {
 
 GType uobject_exportable_get_type(void);
 
+/*
+ * Export the object by writing it to the given FILE handle, which must have
+ * been opened for writing in binary mode.
+ */
 int uobject_export(GObject *obj, FILE *f);
+
+/*
+ * Get the suggested output filename.  Not more than n-1 characters of the
+ * filename will be written to buf, and the result is always null terminated.
+ * Returns the number of characters that would be written if the buffer was
+ * not bounded.  It is valid to call this function with a NULL buffer and a 0
+ * size in order to determine how large the buffer needs to be.
+ */
 int uobject_export_name(GObject *obj, char *buf, size_t n);
 
 #endif
diff --git a/src/uobject/loadable.h b/src/uobject/loadable.h
index 90888e9..ff5fd63 100644
--- a/src/uobject/loadable.h
+++ b/src/uobject/loadable.h
@@ -33,6 +33,12 @@
 
 typedef struct UObjectLoadable UObjectLoadable;
 
+/*
+ * Interface for UObjects supporting "load" and "unload".  These are generally
+ * objects that need to allocate large amounts of memory in order to be
+ * useful -- textures and sounds, for example -- where you might want to keep
+ * around instances but the actual texture or sound data is not needed.
+ */
 struct UObjectLoadable {
 	GTypeInterface parent;
 
-- 
2.43.2