more doc/example tweaks

haxe.html.markdown

@@ -650,27 +650,32 @@ class ComplexEnumTest{
 
 class TypedefsAndStructuralTypes {
     public static function example(){
-        // Here we're going to use typedef types, instead of base types.
+        /*
+           Here we're going to use typedef types, instead of base types.
+           At the top we've declared the type "FooString" to mean a "String" type.
+         */
         var t1:FooString = "some string";
 
         /*
-           We can use typedefs for "structural types".  These types are defined
+           We can use typedefs for "structural types" as well.  These types are
-           by their field structure, not by class inheritance.  Here's an
+           defined by their field structure, not by class inheritance.  Here's
-           anonymous object with a String field named "foo":
+           an anonymous object with a String field named "foo":
          */
 
-        var fooObj = { foo: 'hi' };
+        var anon_obj = { foo: 'hi' };
 
         /*
-           Remember back at the top where we declared the FooObj typedef?
+           The anon_obj variable doesn't have a type declared, and is an
-           Since fooObj matches that structure, we can use it anywhere that
+           anonymous object according to the compiler.  However, remember back at
-           a "FooObject" is expected.
+           the top where we declared the FooObj typedef?  Since anon_obj matches
+           that structure, we can use it anywhere that a "FooObject" type is
+           expected.
          */
 
         var f = function(fo:FooObject){
             trace('$fo was passed in to this function');
         }
-        f(fooObj); // call the FooObject signature function with fooObj.
+        f(anon_obj); // call the FooObject signature function with anon_obj.
 
         /*
            Note that typedefs can have optional fields as well, marked with "?"