Documentation tidyups

git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@14298 72102866-910b-0410-8b05-ffd578937521

Source/NSDebug.m

@@ -90,6 +90,17 @@ static const char*	_GSDebugAllocationListAll();
 
 @end
 
+/**
+ * This function is a GNUstep extension.  It activates or
+ * deactivates object allocation debugging.  Returns the
+ * previous state.  You should call this function to activate
+ * allocation debugging before using any of the functions
+ * described in this section.  Object allocation debugging
+ * should not affect performance too much, and is very useful
+ * as it allows you to monitor how many objects of each class
+ * your application has allocated.  See below for a detailed
+ * description of the info you can get, and why it is useful.
+ */
 BOOL
 GSDebugAllocationActive(BOOL active)
 {
@@ -100,6 +111,22 @@ GSDebugAllocationActive(BOOL active)
   return old;
 }
 
+/**
+ * This function is a GNUstep extension.  It activates
+ * tracking all allocated instances of the specified class
+ * (passed as argument).  This tracking can slow your
+ * application down, so you should use it only when you are
+ * into serious debugging.  Usually, you will monitor your
+ * application by using the functions GSDebugAllocationList
+ * and similia (see above), which do not slow things down
+ * much and return the number of allocated instances; when
+ * (if) by studying the reports generated by these functions
+ * you have found a leak of objects of a certain class, and
+ * if you can't figure out how to fix it by looking at the
+ * code, you can use this function to start tracking
+ * allocated instances of that class, and the following one
+ * can sometime allow you to list the leaked objects directly.
+ */
 void
 GSDebugAllocationActiveRecordingObjects(Class c)
 {
@@ -251,6 +278,29 @@ GSDebugAllocationAdd(Class c, id o)
     }
 }
 
+/**
+ * <p>
+ *   This function is a GNUstep extension.  Returns the number
+ *   of instances of the specified class which are currently
+ *   allocated.  This number is very important to detect memory
+ *   leaks.  If you notice that this number is constantly
+ *   increasing without apparent reason, it is very likely a
+ *   memory leak - you need to check that you are correctly
+ *   releasing objects of this class, otherwise when your
+ *   application runs for a long time, it will eventually
+ *   allocate so many objects as to eat up all your system's
+ *   memory ...
+ * </p>
+ * <p> 
+ *   This function, like the ones below, returns the number of
+ *   objects allocated/released from the time when
+ *   GSDebugAllocationActive was first called.  A negative
+ *   number means that in total, there are less objects of this
+ *   class allocated now than there were when you called
+ *   GSDebugAllocationActive; a positive one means there are
+ *   more.
+ * </p>
+ */
 int
 GSDebugAllocationCount(Class c)
 {
@@ -266,6 +316,23 @@ GSDebugAllocationCount(Class c)
   return 0;
 }
 
+/**
+ * This function is a GNUstep extension.  Returns the total
+ * number of instances of the specified class which have been
+ * allocated - basically the number of times you have
+ * allocated an object of this class.  If this number is very
+ * high, it means you are creating a lot of objects of this
+ * class; even if you are releasing them correctly, you must
+ * not forget that allocating and deallocating objects is
+ * usually one of the slowest things you can do, so you might
+ * want to consider whether you can reduce the number of
+ * allocations and deallocations that you are doing - for
+ * example, by recycling objects of this class, uniquing
+ * them, and/or using some sort of flyweight pattern.  It
+ * might also be possible that you are unnecessarily creating
+ * too many objects of this class.  Well - of course some times
+ * there is nothing you can do about it.
+ */
 int
 GSDebugAllocationTotal(Class c)
 {
@@ -281,6 +348,18 @@ GSDebugAllocationTotal(Class c)
   return 0;
 }
 
+/**
+ * This function is a GNUstep extension.  Returns the peak
+ * number of instances of the specified class which have been
+ * concurrently allocated.  If this number is very high, it
+ * means at some point in time you had a situation with a
+ * huge number of objects of this class allocated - this is
+ * an indicator that probably at some point in time your
+ * application was using a lot of memory - so you might want
+ * to investigate whether you can prevent this problem by
+ * inserting autorelease pools in your application's
+ * processing loops.
+ */
 int
 GSDebugAllocationPeak(Class c)
 {
@@ -296,6 +375,15 @@ GSDebugAllocationPeak(Class c)
   return 0;
 }
 
+/**
+ * This function is a GNUstep extension.  Returns a NULL
+ * terminated array listing all the classes for which
+ * statistical information has been collected.  Usually, you
+ * call this function, and then loop on all the classes returned,
+ * and for each one you get current, peak and total count by
+ * using GSDebugAllocationCount, GSDebugAllocationPeak and
+ * GSDebugAllocationTotal.
+ */
 Class *
 GSDebugAllocationClassList()
 {
@@ -321,11 +409,15 @@ GSDebugAllocationClassList()
   return ans;
 }
 
-/*
- *	This function returns a string listing all those classes for which
- *	either objects are currently allocated (difference == 0), or there
- *	has been a change in the number of objects allocated since the last
- *	call (difference != 0).
+/**
+ * This function is a GNUstep extension.  Returns a newline
+ * separated list of the classes which have instances
+ * allocated, and the instance counts.  If the 'changeFlag'
+ * argument is YES then the list gives the number of
+ * instances allocated/deallocated since the function was
+ * last called.  This function only returns the current count
+ * of instances (not the peak or total count), but its output
+ * is ready to be displayed or logged.
  */
 const char*
 GSDebugAllocationList(BOOL changeFlag)
@@ -415,6 +507,15 @@ _GSDebugAllocationList(BOOL difference)
   return buf;
 }
 
+/**
+ * This function is a GNUstep extension.  Returns a newline
+ * separated list of the classes which have had instances
+ * allocated at any point, and the total count of the number
+ * of instances allocated for each class.  The difference with
+ * GSDebugAllocationList is that this function returns also
+ * classes which have no objects allocated at the moment, but
+ * which had in the past.
+ */
 const char*
 GSDebugAllocationListAll()
 {
@@ -537,6 +638,16 @@ GSDebugAllocationRemove(Class c, id o)
     }
 }
 
+/**
+ * This function is a GNUstep extension.  Returns an array
+ * containing all the allocated objects of a certain class
+ * which have been recorded (to start the recording, you need
+ * to invoke GSDebugAllocationActiveRecordedObjects).
+ * Presumably, you will immediately call -description on them
+ * to find out the objects you are leaking.  The objects are
+ * returned in an array, so until the array is autoreleased,
+ * the objects are not released.
+ */
 NSArray *
 GSDebugAllocationListRecordedObjects(Class c)
 {