diff --git a/SWIG/Doc/Manual/Java.html b/SWIG/Doc/Manual/Java.html
index 494846c87..d93dd3cd4 100644
--- a/SWIG/Doc/Manual/Java.html
+++ b/SWIG/Doc/Manual/Java.html
@@ -2805,8 +2805,9 @@ int c = example.count('e',"Hello World");
 <a name="n52"></a><H3>15.7.4 Typemaps for mapping C/C++ types to Java types</H3>
 
 
-The typemaps available to the Java module include the common typemaps listed in the main typemaps section. There are a number of additional typemaps which can be used with Java.
-The most important of these implement the mapping of C/C++ types to Java types. There are three of them:
+The typemaps available to the Java module include the common typemaps listed in the main typemaps section. 
+There are a number of additional typemaps which are necessary for using SWIG with Java.
+The most important of these implement the mapping of C/C++ types to Java types:
 
 <br>&nbsp;
 <table BORDER>
@@ -2848,6 +2849,18 @@ The most important of these implement the mapping of C/C++ types to Java types.
 </tr>
 </table>
 
+<p>
+If you are writing your own typemaps to handle a particular type, you will normally have to write a collection of them. 
+The default typemaps are in <tt>java.swg</tt> and so might be a good place for finding typemaps to base any new ones on.</li>
+
+<p>
+The "jni", "jtype" and "jstype" typemaps are usually defined together to handle the Java to C/C++ type mapping.
+An "in" typemap should be accompanied by a "javain" typemap and likewise an "out" typemap by a "javaout" typemap.
+If an "in" typemap is written, a "freearg" and "argout" typemap may also need to be written
+as some types have a default "freearg" and/or "argout" typemap which may need overriding. 
+The "freearg" typemap sometimes releases memory allocated by the "in" typemap. 
+The "argout" typemap sometimes sets values in function parameters which are passed by reference in Java. 
+
 <p>The default code generated by SWIG for the Java module comes from the typemaps in the <tt>java.swg</tt> library file which implements the 
 <a href="#n49">Default primitive type mappings</a>
 covered earlier.
@@ -2967,17 +2980,6 @@ is released afterwards</td>
 </tr>
 </table>
 
-<p>
-If you are writing your own typemaps to handle a particular type, you will normally have to write a collection of them. 
-Take a look at the default typemaps in <tt>java.swg</tt>.</li>
-<p>
-The "jni", "jtype" and "jstype" typemaps are usually defined together to handle the Java to C/C++ type mapping.
-An "in" typemap is usually accompanied by a "javain" typemap and likewise an "out" typemap with a "javaout" typemap.
-If an "in" typemap is written, a "freearg" and "argout" typemap may also need to be written. 
-as some types have a default "freearg" and/or "argout" typemap which may need overriding. 
-The "freearg" typemap sometimes releases memory allocated by the "in" typemap. 
-The "argout" typemap sometimes sets values in function parameters which are passed by reference in Java. 
-
 <a name="n53"></a><H3>15.7.5 Java special variables</H3>
 
 
@@ -3553,6 +3555,10 @@ public:
     }
 ...
 };
+
+Vehicle *vehicle_factory() {
+    return new Ambulance("Very loud");
+}
 </pre></blockquote>
 
 If we execute the following Java code:
@@ -3575,8 +3581,8 @@ java.lang.ClassCastException
 
 Even though we know from examination of the C++ code that <tt>vehicle_factory</tt> returns an object of type <tt>Ambulance</tt>, 
 we are not able to use this knowledge to perform the downcast in Java.
-This occurs because the runtime type information is not completely passed from C++ to Java when returning the type from <tt>vehicle_factory</tt>.
-Usually this is not a problem as virtual functions, as in the case of <tt>start</tt> work. 
+This occurs because the runtime type information is not completely passed from C++ to Java when returning the type from <tt>vehicle_factory()</tt>.
+Usually this is not a problem as virtual functions do work by default, such as in the case of <tt>start()</tt>. 
 There are a few solutions to getting downcasts to work.
 <p>