From c1c64ddc9a44d6ff2a79e5a7a8aa69e02e0d1331 Mon Sep 17 00:00:00 2001
From: skyjake <skyjake@users.sourceforge.net>
Date: Tue, 1 May 2012 20:55:43 +0300
Subject: [PATCH] Documentation: Improved apidoc for Garbage

---
 doomsday/engine/portable/include/garbage.h | 24 +++++++++++++++-------
 1 file changed, 17 insertions(+), 7 deletions(-)

diff --git a/doomsday/engine/portable/include/garbage.h b/doomsday/engine/portable/include/garbage.h
index bdc8148a97..63865e9271 100644
--- a/doomsday/engine/portable/include/garbage.h
+++ b/doomsday/engine/portable/include/garbage.h
@@ -33,20 +33,30 @@
 extern "C" {
 #endif
 
+/**
+ * Recycles all collected garbage and deletes the collectors. Called at engine
+ * shutdown. Should be called in the main thread.
+ */
 void Garbage_Shutdown(void);
 
+/**
+ * Recycles all garbage of the current thread and deletes the thread's garbage
+ * collector. Should be called right before the thread ends.
+ */
 void Garbage_ClearForThread(void);
 
 /**
- * Puts a region of allocated memory up for garbage collection. The memory
- * will be available for use until Garbage_Recycle() is called.
+ * Puts a region of allocated memory up for garbage collection in the current
+ * thread. The memory will be available for use until Garbage_Recycle() is
+ * called.
  *
  * @param ptr  Pointer to memory. Can be allocated with malloc() or Z_Malloc().
  */
 void Garbage_Trash(void* ptr);
 
 /**
- * Determines whether a memory pointer has been trashed.
+ * Determines whether a memory pointer has been trashed. Only the current
+ * thread's collector is searched.
  *
  * @param ptr  Pointer to memory.
  *
@@ -55,16 +65,16 @@ void Garbage_Trash(void* ptr);
 boolean Garbage_IsTrashed(const void* ptr);
 
 /**
- * Removes a region from the trash, if it is still there.
- * @warning Do not call this if there is a chance that the pointer has
- * already been freed.
+ * Removes a region from the current thread's collector, if it is still there.
+ * @warning Do not call this if there is a chance that the pointer has already
+ * been freed.
  *
  * @param ptr  Pointer to memory allocated from the @ref memzone.
  */
 void Garbage_Untrash(void* ptr);
 
 /**
- * Frees all pointers given over to the garbage collector.
+ * Frees all pointers given over to the current thread's garbage collector.
  */
 void Garbage_Recycle(void);