From 7c4efe5f2a09a375e6ad217610d7a5eb6a92b213 Mon Sep 17 00:00:00 2001
From: Mike Gerwitz <mike@mikegerwitz.com>
Date: Tue, 15 Mar 2011 00:31:09 -0400
Subject: [PATCH] Added section on temporary classes

---
 doc/classes.texi | 44 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/doc/classes.texi b/doc/classes.texi
index 7c78e68..e71c60a 100644
--- a/doc/classes.texi
+++ b/doc/classes.texi
@@ -133,6 +133,7 @@ capital, for class names (and nothing else).
 
 @menu
 * Anonymous vs. Named Classes::
+* Temporary Classes::  Throwaway classes that only need to be used once
 @end menu
 
 
@@ -200,3 +201,46 @@ functionally no difference between named and anonymous classes.}
 Much better! We now have a useful error message and immediately know which class
 is causing the issue.
 
+
+@node Temporary Classes
+@subsection Temporary Classes
+In @ref{f:class-easejs,}, we saw that the @code{new} keyword was unnecessary
+when instantiating classes. This permits a form of shorthand that is very useful
+for creating @dfn{temporary classes}, or ``throwaway`` classes which are used
+only once.
+
+Consider the following example:
+
+@float Figure, f:class-tmp
+@verbatim
+    // new instance of anonymous class
+    var foo = Class(
+    {
+        'public bar': function()
+        {
+            return 'baz';
+        }
+    } )();
+
+    foo.bar(); // returns 'baz'
+@end verbatim
+@caption{Declaring a temporary (throwaway) class}
+@end float
+
+In @ref{f:class-tmp,} above, rather than declaring a class, storing that in a
+variable, then instantiating it separately, we are doing it in a single command.
+Notice the parenthesis at the end of the statement. This invokes the
+constructor. Since the @code{new} keyword is unnecessary, a new instance of the
+class is stored in the variable @var{foo}.
+
+We call this a temporary class because it is used only to create a single
+instance. The class is then never referenced again. Therefore, we needn't even
+store it - it's throwaway.
+
+The downside of this feature is that it is difficult to notice unless the reader
+is paying very close attention. There is no keyword to tip them off. Therefore,
+it is very important to clearly document that you are storing an instance in the
+variable rather than an actual class definition. If you follow the CamelCase
+convention for class names, then simply do not capitalize the first letter of
+the destination variable for the instance.
+