update documentation

1 files changed, 26 insertions, 64 deletions

diff --git a/documentation/constructors-and-destructors.html b/documentation/constructors-and-destructors.html
index 42a6699..8b9211f 100644
--- a/documentation/constructors-and-destructors.html
+++ b/documentation/constructors-and-destructors.html
@@ -5,59 +5,21 @@
 </p>
 <p>
     A C++ constructor is called on an object that is <i>being</i> initialized,
-    but that is <i>not</i> in an initialized state <i>yet</i>. You can experience this by
-    calling a pure virtual method from a constructor. This will make your 
-    program crash, even when the pure virtual method was implemented in the
-    derived class. The reason for this is that inside the C++ constructor the 
-    object is not yet fully initialized, and the object is not yet aware of 
-    it's position in the class hierarchy. The call to the pure virtual method 
-    can thus not be passed on to the derived object.
+    but that is <i>not</i> in an initialized state <i>yet</i>. You can experience 
+    this by calling a virtual method from the constructor. Even when this virtual 
+    method was overridden in a derived class, this will always execute the method 
+    of the class itselves, and not the overridden implementation. The reason 
+    for this is that during the call to the C++ constructor the object is not yet 
+    fully initialized, and the object is not yet aware of it's position in the 
+    class hierarchy. The call to the virtual method can thus not be passed 
+    on to the derived object.
 </p>
 <p>
-<pre class="language-c++"><code>
-#include &lt;iostream&gt;
-
-// define a base class with a pure virtual method that is called from the
-// constructor
-class BASE 
-{
-public:
-    // constructor
-    BASE() 
-    {
-        // call the pure virtual method
-        doSomething();
-    }
-    
-    // define method that should be implemented by derived classes
-    virtual void doSomething() = 0;
-};
-
-// define a derived class
-class DERIVED : public BASE 
-{
-public:
-    // implementation of the virtual function
-    virtual void doSomething() override 
-    {
-        std::cout &lt;&lt; "doSomething()" &lt;&lt; std::endl;
-    }
-};
-
-// main procedure
-int main()
-{
-    DERIVED d;
-    return 0;
-}
-</code></pre>
-</p>
-<p>
-    The above program crashes (some compilers even refuse to compile this). 
-    In PHP however, when the __construct() method 
-    gets called, the object is already fully initialized and it is perfectly 
-    legal to make calls to abstract methods that are implemented in derived 
-    classes, as you can see in the following example.
+    In PHP however, the __construct() method has a different behavior. When
+    it gets called, the object is already fully initialized and it is perfectly 
+    legal to make calls to even abstract methods that are implemented in derived 
+    classes. The following PHP script is completely legal - but it is impossible
+    to do a similar thing in C++.
 </p>
 <p>
 <pre class="language-php"><code>
@@ -93,22 +55,22 @@ $d = new DERIVED();
 </code></pre>
 </p>
 <p>
-    This PHP script correctly outputs 'doSomething()'. This happens because the 
-    __construct() method in PHP does not really construct anything, it 
-    has access to all members, and (when available) 
-    also the base class and overridden methods. In fact, __construct() is not a 
-    constructor at all, but a very
-    normal method that just happens to be the first method that is called right 
-    after the object is constructed, and that is called automatically.
+    This script outputs 'doSomething()'. In fact, __construct() is not a 
+    constructor at all, but a very normal method that just happens to be the 
+    first method that is called, and that is called automatically after the
+    object is constructed.
 </p>
 <p>
     This difference is important for you as a C++ programmer, because you should
-    never confuse your C++ constructor with the __construct() method. In the C++
-    constructor, the C++ object is being constructed and the
-    PHP object does not yet exist. After the constructor is finished, the PHP engine
-    will create the PHP object, and the PHP-CPP library will link that PHP object
-    to your C++ class. And only then the __construct() method gets called. It is therefore
-    valid to have both a C++ constructor and a __construct() method in your class.
+    never confuse your C++ constructor with the PHP __construct() method. In the C++
+    constructor, the object is being constructed and the PHP object does not 
+    yet exist. After the constructor is finished, the PHP engine
+    takes over control and creates the PHP object, and the PHP-CPP library then 
+    links that PHP object to your C++ object. Only after both the PHP object and
+    the C++ object are fully constructed, the __construct() method is called - just 
+    like a normal method. It is therefore not uncommon to have both a C++ constructor 
+    and a __construct() method in your class. The C++ constructor to initialize
+    the member variables, and __construct() to activate the object.
 </p>
 <p>
 <pre class="language-c++"><code>