Document logging capabilities.

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

ChangeLog

@@ -1,7 +1,9 @@
 2002-10-09  Richard Frith-Macdonald <rfm@gnu.org>
 
+	* Source/NSLog.m: Lots of documentation added.
 	* Tools/GNUmakefile: build autogsdoc documentation automatically
 	if possible.
+	* Tools/AGSOutput.m: Make automatic cross references for functions.
 
 2002-10-08  Richard Frith-Macdonald <rfm@gnu.org>
 

Headers/gnustep/base/NSObjCRuntime.h

@@ -1,4 +1,4 @@
-/* Interface to ObjC runtime for GNUStep
+/** Interface to ObjC runtime for GNUStep
    Copyright (C) 1995, 1997, 2000 Free Software Foundation, Inc.
 
    Written by:  Andrew Kachites McCallum <mccallum@gnu.ai.mit.edu>
@@ -19,6 +19,10 @@
    You should have received a copy of the GNU Library General Public
    License along with this library; if not, write to the Free
    Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 USA.
+
+    AutogsdocSource: NSObjCRuntime.m
+    AutogsdocSource: NSLog.m
+
    */ 
 
 #ifndef __NSObjCRuntime_h_GNUSTEP_BASE_INCLUDE
@@ -55,12 +59,17 @@ GS_EXPORT NSString	*NSStringFromClass(Class aClass);
 GS_EXPORT const char	*NSGetSizeAndAlignment(const char *typePtr,
   unsigned int *sizep, unsigned int *alignp);
 
+#ifndef	NO_GNUSTEP
 /* Logging */
 /* OpenStep spec states that log messages go to stderr, but just in case
    someone wants them to go somewhere else, they can implement a function
    like this */
 typedef void NSLog_printf_handler (NSString* message);
 GS_EXPORT NSLog_printf_handler	*_NSLog_printf_handler;
+GS_EXPORT int	_NSLogDescriptor;
+@class NSRecursiveLock;
+GS_EXPORT NSRecursiveLock	*GSLogLock();
+#endif
 
 GS_EXPORT void			NSLog (NSString* format, ...);
 GS_EXPORT void			NSLogv (NSString* format, va_list args);

Source/NSLog.m

@@ -46,7 +46,36 @@
 
 #include "GSPrivate.h"
 
-int _NSLogDescriptor = 2;	// Default descriptor for logging
+/**
+ * A variable holding the file descriptor to which NSLogv() messages are
+ * written by default.  GNUstep initialises this to stderr.<br />
+ * You may change this, but for thread safety should
+ * use the lock provided by GSLogLock() to protect the change.
+ */
+int _NSLogDescriptor = 2;
+
+static NSRecursiveLock	*myLock = nil;
+
+/**
+ * Returns the lock used to protect the GNUstep NSLogv() implementation.
+ * Use this to protect changes to
+ * <ref type="variable" id="_NSLogDescriptor">_NSLogDescriptor</ref> and
+ * <ref type="variable" id="_NSLog_printf_handler">_NSLog_printf_handler</ref>
+ */
+NSRecursiveLock *
+GSLogLock()
+{
+  if (myLock == nil)
+    {
+      [gnustep_global_lock lock];
+      if (myLock == nil)
+	{
+	  myLock = [NSRecursiveLock new];
+	}
+      [gnustep_global_lock unlock];
+    }
+  return myLock;
+}
 
 static void
 _NSLog_standard_printf_handler (NSString* message)
@@ -111,8 +140,50 @@ _NSLog_standard_printf_handler (NSString* message)
 #endif
 }
 
+/**
+ * A pointer to a function used to actually write the log data.
+ * <p>
+ *   GNUstep initialises this to a function implementing the standard
+ *   behavior for logging, but you may change this in your program
+ *   in order to implement any custom behavior you wish.  You should
+ *   use the lock returned by GSLogLock() to protect any change you make.
+ * </p>
+ * <p>
+ *   Calls from NSLogv() to the function pointed to by this variable
+ *   are protected by a lock, and should therefore be thread safe.
+ * </p>
+ * <p>
+ *   This function should accept a single NSString argument and return void.
+ * </p>
+ * The default implementation in GNUstep performs as follows -
+ * <list>
+ *   <item>
+ *     Converts the string to be logged to data in the default CString
+ *     encoding or, if that is not possible, to UTF8 data.
+ *   </item>
+ *   <item>
+ *     If the system supports writing to syslog and the user default to
+ *     say that logging should be done to syslog (GSLogSyslog) is set,
+ *     writes the data to the syslog.
+ *   </item>
+ *   <item>
+ *     Otherwise, writes the data to the file descriptor stored in the
+ *     variable
+ *     <ref type="variable" id="_NSLogDescriptor">_NSLogDescriptor</ref>,
+ *     which is set by default to stderr.<br />
+ *     Your program may change this descriptor ... but you should protect
+ *     changes using the lock provided by GSLogLock().<br />
+ *     NB. If the write to the descriptor fails, and the system supports
+ *     writing to syslog, then the log is written to syslog as if the
+ *     appropriate user default had been set.
+ *   </item>
+ * </list>
+ */
 NSLog_printf_handler *_NSLog_printf_handler = _NSLog_standard_printf_handler;
 
+/**
+ * Provides a standard logging facility via NSLogv().
+ */
 void 
 NSLog (NSString* format, ...)
 {
@@ -123,13 +194,32 @@ NSLog (NSString* format, ...)
   va_end (ap);
 }
 
+/**
+ * The core logging function ...
+ * <p>
+ *   The function generates a standard log entry by prepending
+ *   process ID and date/time information to your message, and
+ *   ensuring that a newline is present at the end of the message.
+ * </p>
+ * <p>
+ *   The resulting message is then passed to a handler function to
+ *   perform actual output.  Locking is performed around the call to
+ *   the function actually writing the message out, to ensure that
+ *   logging is thread-safe.  However, the actual creation of the
+ *   message written is only as safe as the -description methods of
+ *   the arguments you supply.
+ * </p>
+ * <p>
+ *   The function to write the data is pointed to by
+ *   <ref type="variable" id="_NSLog_printf_handler">_NSLog_printf_handler</ref>
+ * </p>
+ */
 void 
 NSLogv (NSString* format, va_list args)
 {
-  static NSRecursiveLock	*myLock = nil;
-  NSString			*prefix;
-  NSString			*message;
-  int				pid;
+  NSString	*prefix;
+  NSString	*message;
+  int		pid;
   CREATE_AUTORELEASE_POOL(arp);
 
   if (_NSLog_printf_handler == NULL)
@@ -162,13 +252,9 @@ NSLogv (NSString* format, va_list args)
 
   if (myLock == nil)
     {
-      [gnustep_global_lock lock];
-      if (myLock == nil)
-	{
-	  myLock = [NSRecursiveLock new];
-	}
-      [gnustep_global_lock unlock];
+      GSLogLock();
     }
+
   [myLock lock];
 
   _NSLog_printf_handler(prefix);

Source/NSUserDefaults.m

@@ -86,6 +86,7 @@ static void updateCache(NSUserDefaults *self)
   if (self == sharedDefaults)
     {
       NSArray	*debug;
+      NSString	*s;
 
       /**
        * If there is an array NSUserDefault called GNU-Debug,
@@ -105,6 +106,7 @@ static void updateCache(NSUserDefaults *self)
 	      [s addObject: level];
 	    }
 	}
+
       flags[GSMacOSXCompatible]
 	= [self boolForKey: @"GSMacOSXCompatible"];
       flags[GSOldStyleGeometry]

Tools/AGSOutput.m

@@ -2097,16 +2097,17 @@ static BOOL snuggleStart(NSString *t)
 	    && [str isEqual: @"main"] == NO)
 	    {
 	      ok = YES;
-	      if (len > r.location + 2)
+	      if (len > NSMaxRange(r))
 		{
 		  NSString	*end;
 
-		  end = [tmp substringFromIndex: r.location + 2];
+		  end = [tmp substringFromIndex: NSMaxRange(r)];
 		  c = [end characterAtIndex: 0];
 		  if (c == ',' || c == '.' || c == ';')
 		    {
 		      [a insertObject: end atIndex: l + 1];
-		      tmp = [tmp substringToIndex: r.location + 2];
+		      tmp = [tmp substringToIndex: NSMaxRange(r)];
+		      [a replaceObjectAtIndex: l withObject: tmp];
 		    }
 		  else
 		    {