--- a/Message.st	Tue Apr 23 16:40:11 1996 +0200
+++ b/Message.st	Tue Apr 23 16:47:53 1996 +0200
@@ -35,21 +35,40 @@
 
 documentation
 "
-    Instances of Message are only created, when a message send fails 
+    Instances of Message represent a message being sent.
+    During normal execution, message objects are NEVER used -
+    instead, argument passing is done more performant via the stack
+    or in registers (depends on how your C compiler passes arguments).
+
+    However, messageObjects ARE created, when a message send fails 
     (i.e. some message is not understood).
-    In this case, the selector and arguments are put into an instance of 
-    Message, which is then passed to #doesNotUnderstand: as argument.
+    In this case, the selector and arguments of the failing messare
+    are squashed into a new instance of Message, and a #doesNotUnderstand: 
+    message is sent to the original receiver, passing the message object
+    as argument.
 
-    Typically, Object>>doesNotUnderstand: is evaluated, which starts up
-    a debugger, but it is possible to redefine this method, which
-    allows for re-evaluation of the failed send (after some cleanup).
+    Typically, #doesNotUnderstand: is not redefined in the receivers class,
+    therefore Object>>doesNotUnderstand: gets evaluated.
+    There, a debugger is opened and the thread is suspended.
+    However, it is possible to redefine this method, which
+    allows for re-evaluation of the failed send (after some cleanup),
+    to upload some code or to simply ignore the error.
 
     As an example of its use, see the implementation of the Autoload-class,
     or how ScrollableView forwards unknown messages to its slave-view.
 
+    Elegance hint: actually, Object>>doesNotUnderstand: raises an exception
+    which can be handled - in most situations, providing an exception handler 
+    instead of redefining #doesNotUnderstand is the better way to do things.
+
+
     Notice:
-    Since the layout of Message-objects is known by the runtime system, it is 
-    not allowed to change the definition of this class.
+    Since the layout of Message-objects is known by the runtime system
+    (it has to create those objects in case of a failure)
+    it is not allowed to change the definition of this class.
+
+    [See also:]
+        Signal  Exception  MessageSend
 "
 ! !
 
@@ -160,5 +179,5 @@
 !Message class methodsFor:'documentation'!
 
 version
-    ^ '$Header: /cvs/stx/stx/libbasic/Message.st,v 1.17 1996-04-23 14:03:56 cg Exp $'
+    ^ '$Header: /cvs/stx/stx/libbasic/Message.st,v 1.18 1996-04-23 14:47:53 cg Exp $'
 ! !