[Gnash-commit] /srv/bzr/gnash/trunk r11745: More documentation.

[Benjamin Wolsey]

------------------------------------------------------------
revno: 11745 [merge]
committer: Benjamin Wolsey <address@hidden>
branch nick: trunk
timestamp: Mon 2010-01-11 16:15:54 +0100
message:
  More documentation.
modified:
  libcore/as_object.h

=== modified file 'libcore/as_object.h'
--- a/libcore/as_object.h       2010-01-11 12:38:41 +0000
+++ b/libcore/as_object.h       2010-01-11 15:04:04 +0000
@@ -27,15 +27,15 @@
 #include "string_table.h"
 #include "GC.h" // for inheritance from GcResource (to complete)
 #include "PropertyList.h"
-#include "as_value.h" // for return of get_primitive_value
+#include "as_value.h" 
 #include "smart_ptr.h"
-#include "PropFlags.h" // for enum
+#include "PropFlags.h"
 #include "GnashException.h"
 #include "Relay.h"
 #include "ObjectURI.h"
 
 #include <cmath>
-#include <utility> // for std::pair
+#include <utility> 
 #include <set>
 #include <sstream>
 #include <boost/scoped_ptr.hpp>
@@ -139,13 +139,41 @@
 
 };
 
-
-/// \brief
-/// A generic bag of attributes. Base class for all ActionScript-able objects.
-//
-/// Base-class for ActionScript script-defined objects.
-/// This would likely be ActionScript's 'Object' class.
-///
+/// The base class for all ActionScript objects
+//
+/// Everything in ActionScript is an object or convertible to an object. This
+/// class is the base class for all object types and the implementation of the
+/// ActionScript Object type itself. See asobj/Object.cpp for the ActionScript
+/// Object interface.
+//
+/// An AS2 object has 3 principle tasks:
+//
+/// 1. to store a set of ActionScript properties and to control dynamic access
+///    to them.
+/// 2. to store native type information.
+/// 3. to store 'watches' that report on changes to any member property.
+//
+/// A fourth but relatively minor task is to store a list of implemented
+/// interfaces (see as_object::instanceOf()).
+//
+/// ActionScript has two different levels of Object typing:
+//
+/// Dynamic Typing
+//
+/// 1a. Native type information, stored in a Relay and inaccessible
+///     to ActionScript.
+/// 1b. Array type information. This is very similar (and possibly identical
+///     to) Relays.
+/// 2.  Link to a DisplayObject.
+//
+/// Both these dynamic types can be changed independently at runtime using
+/// native functions (often, but not always, constructor functions).
+//
+/// Static Typing
+//
+/// Functions (as_function), Super objects (as_super) and AS3 Class types
+/// (as_class) have a static type, that is, they are not convertible to each
+/// other once created.
 class as_object : public GcResource, boost::noncopyable
 {