--- a/ExternalLong.st	Tue Dec 07 12:27:58 2010 +0100
+++ b/ExternalLong.st	Mon Dec 20 16:29:36 2010 +0100
@@ -43,19 +43,48 @@
 !ExternalLong class methodsFor:'instance creation'!
 
 new
+    "allocate some memory usable for data;
+     the memory is not controlled by the garbage collector.
+     Return a corresponding ExternalBytes object or raise MallocFailure (if malloc fails).
+
+     Use this, if you have to pass a block of bytes to some
+     external destination (such as a C function) which does not copy the
+     data, but instead keeps a reference to it. For example, many functions
+     which expect strings simply keep a ref to the passed string - for those,
+     an ST/X string-pointer is not the right thing to pass, since ST/X objects
+     may change their address.
+
+     DANGER ALERT: the memory is NOT automatically freed until it is either
+                   MANUALLY freed (see #free) or the returned externalBytes object
+                   is unprotected or the classes releaseAllMemory method is called."
+
     ^ super new:4
 
     "
      ExternalLong new
     "
+
+    "Modified: / 20-12-2010 / 16:22:51 / cg"
 !
 
 unprotectedNew
+    "allocate some memory usable for data;
+     the memory is under the control of the garbage collector.
+     Return a corresponding ExternalBytes object or raise MallocFailure (if malloc fails).
+
+     DANGER ALERT: the memory block as allocated will be automatically freed
+                   as soon as the reference to the returned externalBytes object
+                   is gone (by the next garbage collect).
+                   If the memory has been passed to a C-function which
+                   remembers this pointer, bad things may happen ...."
+
     ^ super unprotectedNew:4
 
     "
      ExternalLong new
     "
+
+    "Modified: / 20-12-2010 / 16:22:39 / cg"
 ! !
 
 !ExternalLong methodsFor:'accessing'!
@@ -125,9 +154,9 @@
 !ExternalLong class methodsFor:'documentation'!
 
 version
-    ^ '$Header: /cvs/stx/stx/libbasic2/ExternalLong.st,v 1.7 2010-07-08 14:12:50 stefan Exp $'
+    ^ '$Header: /cvs/stx/stx/libbasic2/ExternalLong.st,v 1.8 2010-12-20 15:29:36 cg Exp $'
 !
 
 version_CVS
-    ^ '$Header: /cvs/stx/stx/libbasic2/ExternalLong.st,v 1.7 2010-07-08 14:12:50 stefan Exp $'
+    ^ '$Header: /cvs/stx/stx/libbasic2/ExternalLong.st,v 1.8 2010-12-20 15:29:36 cg Exp $'
 ! !