--- a/dox/Android.h	Sun Nov 22 14:18:09 2009 +0800
+++ b/dox/Android.h	Sun Nov 22 16:09:06 2009 +0800
@@ -3,62 +3,68 @@
  * I think almost all technical guys know Android, the mobile OS
  * project from Google.  Once I know Android, my first idea is it is
  * cool if Android programmers can be powered by MadButterfly.
- * MadButterfly is very feasible for a lof of programs running on
- * devices that Android targets for.  This document is about how the
- * MadButterfly been integrated with Android and power Android
+ * MadButterfly is very feasible for a lot of programs running on
+ * devices that Android be targeted for.  This document is about how
+ * the MadButterfly is integrated with Android and power Android
  * applications.
  *
  * \section android_jni Android Native Code
  *
  * Android applications are actually Java code running on Dalvik VM.
- * Although, Java bytecode was translated into bytecode of Dalvik.
- * The interface of bytecode running in VM and native code is JNI,
- * just like Java.  So, we must implement a set of API on JNI as the
- * channel for communication between Android applications and
- * MadButterfly.  Following image is how the MadButterfly integrated
- * with the Android.
+ * Although, Java bytecode was translated into Dalvik bytecode.  JNI
+ * is the bridge of bytecode and native code.  Bytecode and native
+ * code can access each other through JNI interface.  So, we must
+ * implement a set of JNI native function as the channel for
+ * communication between Android applications and MadButterfly.
+ * Following image is how the MadButterfly integrated with the
+ * Android.
  *
  * \image html Android-int.png
  *
- * MB JNI is JNI part of MadButterfly for interaction between
- * Madbufferfly and Android applications.  Android applications draw
- * everything on Canvases (backed by a surface).  A canvas is actually
- * bridge to a SkCanvas provided by Skia.  So, MadButterfly can draw
- * on the SkCanvas for drawing on screen.
+ * MB JNI is a set of JNI native static methods that expose
+ * MadButterfly functions to Java code.  Java application can call
+ * native static methods of MB JNI to access functions provided by
+ * MadButterfly.
+ *
+ * Android applications draw everything on Canvas obects (backed by a
+ * surface).  A canvas is actually a wrapper for a SkCanvas of Skia.
+ * Drawing on a Canvas object means drawing on a SkCanvas object.  To
+ * draw on the screen, MadButterfly draws on the SkCanvas.
  *
  * The idea is to make MadButterfly as a View of Android UI.
- * SurfaceView is extended as MBView; the type of view for
- * MadButterfly.  The SurfaceView own a surface.  The surface is
- * passed to MadButterfly as a SurfaceHolder.  MB JNI get Canvas from
- * the SurfaceHolder, and get SkCanvas of Canvas in turn.  With
- * SkCanvas, MadButterfly can draw on the screen for the MBView
- * object.
+ * SurfaceView is extended as MBView; the sub-type of View for showing
+ * graphics generated by MadButterfly.  The SurfaceView own a surface.
+ * The surface is passed to MadButterfly as a SurfaceHolder.  MB JNI
+ * can get Canvas objects from the SurfaceHolder, and get associated
+ * SkCanvas in turn.  With SkCanvas objects, MadButterfly can draw for
+ * the MBView object.
  *
  * \section android_mem Memory Management for Android JNI Interface
  *
  * Some memory allocated and returned by MadButterfly should be
- * managed by the application.  A memory block should not be freed
- * until it is no more used by MadButterfly engine.  It means Android
- * applications reponsible for managing memory blocks.  To simplify
- * implmentation of MB JNI, MB JNI always return the address of an
- * allocated objects as a Java integer.  The Java part should take
- * care about these addresses, and call proper functions for freeing
- * objects specified by addresses.
+ * managed by the application.  These memory blocks should not be
+ * freed until they are no more used by MadButterfly engine.  It means
+ * Android applications reponsible for managing memory blocks.  To
+ * simplify implmentation of MB JNI, MB JNI always return the address
+ * of an allocated objects as a Java integer.  Java code should
+ * take care about these addresses, and call proper functions for
+ * freeing objects specified by addresses at right time.
  *
  * A Java side framework should be designed to easy the work of
- * Android application programmers.  The framework should take care
- * the tracing life-cycle of MadButterfly objects.  The namespace of
- * the framework should be 'org.madbutterfly'.
+ * Android application programmers.  The framework should take care of
+ * tracking life-cycle of MadButterfly objects.  The namespace of the
+ * framework is 'org.madbutterfly'.
  *
  * \section android_jni _jni
  * 
- * org.madbutterfly._jni class is the placeholder to collect JNI APIs
- * for all MadButterfly functions.  All methods of _jni are static.  A
- * method usually maps to a MadButterfly function.  For example,
- * rdman_coord_new() mapes to a MadButterfly function.
+ * org.madbutterfly._jni class is the placeholder to collect JNI
+ * native methods for all MadButterfly functions.  All methods of _jni
+ * are static.  A method usually maps to a MadButterfly function.  For
+ * example, rdman_coord_new() mapes to the MadButterfly function with
+ * the same name.
  *
- * The object returned by a MadButterfly function, for
- * ex. rdman_coord_new(), is casted to a int, the address of the
+ * The object returned by a MadButterfly function, for ex. returned
+ * value of rdman_coord_new(), is casted to a int, the address of the
  * object.  So, type of an argument or return value of an object is
  * declared as a int.  For example,
  * \code
@@ -71,21 +77,20 @@
  *
  * MadButterfly provides only initial function for some objects,
  * application should allocate memory for these function by them-self.
- * For these function, a new JNI interface are used instead of
- * initiali function.  The new JNI interface is responsible for
- * allocating memory and call initial function.  For example,
- * redraw_man_new() is defined as a JNI interface instead of
- * redraw_man_init().
+ * For these function, a new JNI native method are used instead of
+ * initial function.  The new JNI method is responsible for allocating
+ * memory and calling initial function.  For example, redraw_man_new()
+ * is defined as a JNI method instead of redraw_man_init().
  * \code
  *   native static int redraw_man_new(int cr, int backend);
  * \endcode
  * First argument, rdman, of redraw_man_init() is replaced by a int
- * returned value.  cr and backend, mbe_t type by MadButterfly, are
- * now int type by JNI interface.
+ * returned value of redraw_man_new().  cr and backend, mbe_t type by
+ * MadButterfly, are, now, int type by the JNI native method.
  *
  * \section android_java_mb Java Likes MadButterfly
  *
- * To manage life-cycle for MadButterfly objects is not Java likes.
+ * Managing life-cycle for MadButterfly objects is not Java likes.
  * To provie a Java style interface for MadButterfly, a framework to
  * hide underlying life-cycle management is requried.  Life-cycle is
  * one major responsibility of the framework, it should keep integers
@@ -95,10 +100,23 @@
  * For example, org.madbutterfly.redraw_man is the respective Java
  * class of redraw_man_t of MadButterfly engine.  redraw_man has a
  * private member variable redraw_man._rdman_addr.  It is the address
- * of the resptive redraw_man_t object of MadButterfly.  redraw_man
+ * of the respective redraw_man_t object of MadButterfly.  redraw_man
  * would call _jni.redraw_man_destroy() to release associated
- * resources and free the memory before it is recycled.  So,
+ * resources and free the memory before it being recycled.  So,
  * redraw_man.finalize() is defined for releasing resources.  It would
- * be called before the redraw_man object being recycled.
+ * be called before a redraw_man object being recycled.
+ *
+ * \section android_MBView MBView for Android MBView extends
+ *
+ * SurfaceView is a sub-class of View provided by Android.  MBView
+ * inherits SurfaceView to implement a View controlled by
+ * MadButterfly.  A MBView object owns a redraw_man, a.k.a
+ * redraw_man_t of MadButterfly.  Android application programmers
+ * works on redraw_man to manipulate MadButterfly and changes content
+ * showed by the MBView object.  Android applications call
+ * MBView.get_rdman() to retrieve the redraw_man object assocaited
+ * with a MBView object.  MadButterfly would draw the content of a
+ * redraw_man object on the surface, inherited from the SurfaceView
+ * class, associated with the MBView object.
  *
  */