misc reformat, and some small details

haxe.html.markdown

@@ -12,22 +12,29 @@ may be applicable to older versions, but it is recommended to use other
 references.
 
 ```haxe
-// Welcome to Learn Haxe 3 in 15 minutes.  http://www.haxe.org
-// This is an executable tutorial.  You can compile and run it using the haxe
-// compiler, while in the same directory as LearnHaxe.hx:
-// haxe -main LearnHaxe3 -x out
+/*
+   Welcome to Learn Haxe 3 in 15 minutes.  http://www.haxe.org
+   This is an executable tutorial.  You can compile and run it using the haxe
+   compiler, while in the same directory as LearnHaxe.hx:
+   haxe -main LearnHaxe3 -x out
+ */
 
 // Let's start with comments... this is a single line comment
 
 /*
-   And this is multiline
-*/
+   And this is multiline. Multiline comments are also used to generate
+   javadoc-style documentation for haxedoc.  They will be used if they precede
+   a class, class function, or class variable.
+ */
 
-// A package declaration isn't necessary, but it's useful if you want to
-// organize your code into modules later on.  Also worth mentioning, all
-// expressions in Haxe must end in a semicolon:
+/*
+   A package declaration isn't necessary, but it's useful if you want to
+   organize your code into modules later on.  Also worth mentioning, all
+   expressions in Haxe must end in a semicolon:
+ */
 package; // empty package, no namespace.
 
+
 // if you import code from other files, it must be declared before the rest of
 // the code.
 import haxe.ds.ArraySort;
@@ -66,12 +73,14 @@ class LearnHaxe3{
 
         /*
            Trace can handle any type of value or object.  It will try to print
-           a representation of the expression as best it can:
+           a representation of the expression as best it can.  You can also
+           concatenate strings with the "+" operator:
          */
         trace(
             " Integer: " + 10 +
             " Float: " + 3.14 +
-            " Boolean: " + true);
+            " Boolean: " + true
+            );
 
 
         /*
@@ -125,9 +134,12 @@ class LearnHaxe3{
            structures like strings, arrays, lists, and maps:
          */
 
-        var a_string = "some_string";  // strings can have double or single quotes
+        var a_string = "some" + 'string';  // strings can have double or single quotes
         trace(a_string + " is the value for a_string");
 
+        var x = 1;
+        var an_interpolated_string = 'the value of x is $x';
+
         /*
            Strings are immutable, instance methods will return a copy of
            parts or all of the string.
@@ -280,8 +292,10 @@ class LearnHaxe3{
         // while also creating filters and modifications.
         var filtered_n = [for (val in n) if (val != "foo") val];
         trace(filtered_n + " is the value for filtered_n");
+
         var modified_n = [for (val in n) val += '!'];
         trace(modified_n + " is the value for modified_n");
+
         var filtered_and_modified_n = [for (val in n) if (val != "foo") val += "!"];
         trace(filtered_and_modified_n + " is the value for filtered_and_modified_n");
 
@@ -359,26 +373,31 @@ class LearnHaxe3{
         // See documentation for parsing in Std for more details.
 
         //////////////////////////////////////////////////////////////////
-        // Basic Object Oriented Design 
+        // Basic Object Oriented Programming
         //////////////////////////////////////////////////////////////////
-        trace("***BASIC OBJECT ORIENTED DESIGN***");
+        trace("***BASIC OBJECT ORIENTED PROGRAMMING***");
 
 
+        // create an instance of FooClass.  The classes for this are at the
+        // end of the file.
         var instance = new FooClass(3);
+
         // read the public variable normally
         trace(instance.public_any + " is the value for instance.public_any");
 
         // we can read this variable
         trace(instance.public_read + " is the value for instance.public_read");
-        // but not write it, this will throw an error if uncommented:
-        //trace(instance.public_write + " is the value for instance.public_write");
-        // trace(instance.public_write); // vice-versa for public write, etc.
+        // but not write it
+        // instance.public_write = 4; // this will throw an error if uncommented:
+        // trace(instance.public_write); // as will this.
 
         trace(instance + " is the value for instance"); // calls the toString method
+        trace(instance.toString() + " is the value for instance.toString()"); // same thing
 
 
-        // we can successfully pass the FooInstance to the BaseFooClass method,
-        // since it was extended from that.
+        // instance has the "FooClass" type, while acceptBaseFoo has the
+        // BaseFooClass type.  However, since FooClass extends BaseFooClass,
+        // it is accepted.
         BaseFooClass.acceptBaseFoo(instance);
     }
 
@@ -430,6 +449,9 @@ class FooClass extends BaseFooClass implements BaseFooInterface{
     }
 }
 
+/*
+    A simple class to extend
+*/
 class BaseFooClass {
     var base_variable:Int;
     public function new(){
@@ -437,9 +459,11 @@ class BaseFooClass {
     }
     public static function acceptBaseFoo(b:BaseFooClass){
     }
-    
 }
 
+/*
+    A simple interface to implement
+*/
 interface BaseFooInterface{
     public function baseFunction(x:Int):String;
 }