From 089a59ca8ae61006158247f3e3eb4a068c63c559 Mon Sep 17 00:00:00 2001
From: CaS <CaS@72102866-910b-0410-8b05-ffd578937521>
Date: Sat, 28 Jun 2003 05:25:31 +0000
Subject: [PATCH] Better docs

git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@17056 72102866-910b-0410-8b05-ffd578937521
---
 Headers/gnustep/base/GSObjCRuntime.h | 22 +++++++++------
 Source/NSSerializer.m                | 41 ++++++++++++++++++++++++++++
 2 files changed, 55 insertions(+), 8 deletions(-)

diff --git a/Headers/gnustep/base/GSObjCRuntime.h b/Headers/gnustep/base/GSObjCRuntime.h
index e0cae42aa..5e17487f2 100644
--- a/Headers/gnustep/base/GSObjCRuntime.h
+++ b/Headers/gnustep/base/GSObjCRuntime.h
@@ -123,7 +123,7 @@ GSObjCSetValue(NSObject *self, NSString *key, id val, SEL sel,
 
 #define GS_STATIC_INLINE static inline
 
-/*
+/**
  * GSObjCClass() return the class of an instance.
  * The argument to this function must NOT be nil.
  */
@@ -133,7 +133,7 @@ GSObjCClass(id obj)
   return obj->class_pointer;
 }
 
-/*
+/**
  * GSObjCIsInstance() tests to see if an id is an instance.
  * The argument to this function must NOT be nil.
  */
@@ -143,7 +143,7 @@ GSObjCIsInstance(id obj)
   return CLS_ISCLASS(obj->class_pointer);
 }
 
-/*
+/**
  * GSObjCIsKindOf() tests to see if a class inherits from another class
  * The argument to this function must NOT be nil.
  */
@@ -366,28 +366,33 @@ GSFlushMethodCacheForClass (Class class)
 }
 
 
-
+/**
+ * Returns the superclass of this.
+ */
 GS_STATIC_INLINE Class
 GSObjCSuper(Class this)
 {
   return class_get_super_class(this);
 }
 
+/**
+ * Returns the version number of this.
+ */
 GS_STATIC_INLINE int
 GSObjCVersion(Class this)
 {
   return class_get_version(this);
 }
 
-/*
- * Return the zone in which an object belongs, without using the zone method
- */
 #ifndef NeXT_Foundation_LIBRARY
 #include	<Foundation/NSZone.h>
 #else
 #include <Foundation/Foundation.h>
 #endif
 
+/**
+ * Return the zone in which an object belongs, without using the zone method
+ */
 GS_EXPORT NSZone *
 GSObjCZone(NSObject *obj);
 
@@ -397,7 +402,8 @@ GSObjCZone(NSObject *obj);
 GS_EXPORT void *
 GSAutoreleasedBuffer(unsigned size);
 
-/* Getting a system error message on a variety of systems */
+/** Returns a system error message on a variety of systems
+ */
 GS_EXPORT const char *
 GSLastErrorStr(long error_id);
 
diff --git a/Source/NSSerializer.m b/Source/NSSerializer.m
index b1964d497..8dc3ea3e7 100644
--- a/Source/NSSerializer.m
+++ b/Source/NSSerializer.m
@@ -364,6 +364,10 @@ static BOOL	shouldBeCompact = NO;
     }
 }
 
+/**
+ * Converts the supplied propertyList into a serialized representation
+ * in the returned NSData object.
+ */
 + (NSData*) serializePropertyList: (id)propertyList
 {
   _NSSerializerInfo	info;
@@ -377,6 +381,10 @@ static BOOL	shouldBeCompact = NO;
   return info.data;
 }
 
+/**
+ * Converts the supplied propertyList into a serialized representation
+ * stored in d.
+ */
 + (void) serializePropertyList: (id)propertyList
 		      intoData: (NSMutableData*)d
 {
@@ -822,6 +830,16 @@ deserializeFromInfo(_NSDeserializerInfo* info)
     }
 }
 
+/**
+ * <p>Deserializes the property list stored in data at the offset specified
+ * by the value pointed to by cursor.  Upon completion the value in cursor
+ * is updated to refer to a position immediately after the end of the
+ * deserialized sequence.
+ * </p>
+ * <p>The flag is used to specify whether container objects in the
+ * deserialized list should be instances of mutable or immutable classes.
+ * </p>
+ */
 + (id) deserializePropertyListFromData: (NSData*)data
                               atCursor: (unsigned int*)cursor
                      mutableContainers: (BOOL)flag
@@ -846,6 +864,14 @@ deserializeFromInfo(_NSDeserializerInfo* info)
     }
 }
 
+/**
+ * <p>Deserializes the property list stored in data to produce a single
+ * property list object (dictionary, array, string, data, number or date).
+ * </p>
+ * <p>The flag is used to specify whether container objects in the
+ * deserialized list should be instances of mutable or immutable classes.
+ * </p>
+ */
 + (id) deserializePropertyListFromData: (NSData*)data
                      mutableContainers: (BOOL)flag
 {
@@ -869,6 +895,21 @@ deserializeFromInfo(_NSDeserializerInfo* info)
     }
 }
 
+/**
+ * <p>Deserializes the property list stored in data at the offset specified
+ * by the value pointed to by cursor.  Upon completion the value in cursor
+ * is updated to refer to a position immediately after the end of the
+ * deserialized sequence.
+ * </p>
+ * <p>The flag is used to specify whether container objects in the
+ * deserialized list should be instances of mutable or immutable classes.
+ * </p>
+ * <p>The length is used to determine  whether lazy deserialization is done,
+ * if the data is longer than this value, a proxy is returned rather than
+ * the actual property list, and the real deserialization can be done
+ * later.
+ * </p>
+ */
 + (id) deserializePropertyListLazilyFromData: (NSData*)data
                                     atCursor: (unsigned*)cursor
                                       length: (unsigned)length