RubyGems - glib2 - Versions diffs - 2.0.2-x86-mingw32 → 2.0.3-x86-mingw32 - Mend

glib2 2.0.2-x86-mingw32 → 2.0.3-x86-mingw32

Files changed (1609) hide show

data/vendor/local/share/gtk-doc/html/gobject/gtype-instantiable-classed.html CHANGED Viewed

@@ -8,7 +8,7 @@
 <link rel="up" href="chapter-gtype.html" title="The GLib Dynamic Type System">
 <link rel="prev" href="gtype-non-instantiable.html" title="Non-instantiable non-classed fundamental types">
 <link rel="next" href="gtype-non-instantiable-classed.html" title="Non-instantiable classed types: interfaces">
-<meta name="generator" content="GTK-Doc V1.18.1 (XML mode)">
+<meta name="generator" content="GTK-Doc V1.19 (XML mode)">
 <link rel="stylesheet" href="style.css" type="text/css">
 </head>
 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
@@ -283,6 +283,6 @@ void           g_type_free_instance   (GTypeInstance *instance);
 </div>
 <div class="footer">
 <hr>
-          Generated by GTK-Doc V1.18.1</div>
+          Generated by GTK-Doc V1.19</div>
 </body>
 </html>

data/vendor/local/share/gtk-doc/html/gobject/gtype-non-instantiable-classed.html CHANGED Viewed

@@ -8,7 +8,7 @@
 <link rel="up" href="chapter-gtype.html" title="The GLib Dynamic Type System">
 <link rel="prev" href="gtype-instantiable-classed.html" title="Instantiable classed types: objects">
 <link rel="next" href="chapter-gobject.html" title="The GObject base class">
-<meta name="generator" content="GTK-Doc V1.18.1 (XML mode)">
+<meta name="generator" content="GTK-Doc V1.19 (XML mode)">
 <link rel="stylesheet" href="style.css" type="text/css">
 </head>
 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
@@ -373,6 +373,6 @@ maman_ibaz_default_init (MamanIbazInterface *iface)
 </div>
 <div class="footer">
 <hr>
-          Generated by GTK-Doc V1.18.1</div>
+          Generated by GTK-Doc V1.19</div>
 </body>
 </html>

data/vendor/local/share/gtk-doc/html/gobject/gtype-non-instantiable.html CHANGED Viewed

@@ -8,7 +8,7 @@
 <link rel="up" href="chapter-gtype.html" title="The GLib Dynamic Type System">
 <link rel="prev" href="gtype-conventions.html" title="Conventions">
 <link rel="next" href="gtype-instantiable-classed.html" title="Instantiable classed types: objects">
-<meta name="generator" content="GTK-Doc V1.18.1 (XML mode)">
+<meta name="generator" content="GTK-Doc V1.19 (XML mode)">
 <link rel="stylesheet" href="style.css" type="text/css">
 </head>
 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
@@ -71,6 +71,6 @@
 </div>
 <div class="footer">
 <hr>
-          Generated by GTK-Doc V1.18.1</div>
+          Generated by GTK-Doc V1.19</div>
 </body>
 </html>

data/vendor/local/share/gtk-doc/html/gobject/howto-gobject-chainup.html CHANGED Viewed

@@ -8,7 +8,7 @@
 <link rel="up" href="howto-gobject.html" title="How to define and implement a new GObject">
 <link rel="prev" href="howto-gobject-methods.html" title="Object methods">
 <link rel="next" href="howto-interface.html" title="How to define and implement interfaces">
-<meta name="generator" content="GTK-Doc V1.18.1 (XML mode)">
+<meta name="generator" content="GTK-Doc V1.19 (XML mode)">
 <link rel="stylesheet" href="style.css" type="text/css">
 </head>
 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
@@ -32,23 +32,18 @@
 <li class="listitem"><p>In the method B::foo, the child class B calls its parent class method A::foo.</p></li>
 </ul></div>
 <p>
-      There are many uses to this idiom:
+      There are various uses to this idiom:
       </p>
 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
-<li class="listitem"><p>You need to change the behaviour of a class without modifying its code. You create
+<li class="listitem"><p>You need to extend the behaviour of a class without modifying its code. You create
           a subclass to inherit its implementation, re-implement a public virtual method to modify the behaviour
-          slightly and chain up to ensure that the previous behaviour is not really modified, just extended.
+          and chain up to ensure that the previous behaviour is not really modified, just extended.
           </p></li>
-<li class="listitem"><p>You are lazy, you have access to the source code of the parent class but you don't want
-          to modify it to add method calls to new specialized method calls: it is faster to hack the child class
-          to chain up than to modify the parent to call down.</p></li>
 <li class="listitem"><p>You need to implement the Chain Of Responsibility pattern: each object of the inheritance
           tree chains up to its parent (typically, at the beginning or the end of the method) to ensure that
           they each handler is run in turn.</p></li>
 </ul></div>
 <p>
-      I am personally not really convinced any of the last two uses are really a good idea but since this
-      programming idiom is often used, this section attempts to explain how to implement it.
     </p>
 <p>
       To explicitly chain up to the implementation of the virtual method in the parent class,
@@ -56,23 +51,26 @@
       access the original class function pointer and invoke it directly.
       <a href="#ftn.id-1.6.3.8.3.1" class="footnote" name="id-1.6.3.8.3.1"><sup class="footnote">[11]</sup></a>
     </p>
-<p>The function <code class="function"><a class="link" href="gobject-Type-Information.html#g-type-class-peek-parent" title="g_type_class_peek_parent ()">g_type_class_peek_parent</a></code> is used to access the original parent
-    class structure. Its input is a pointer to the class of the derived object and it returns a pointer
-    to the original parent class structure. The code below shows how you could use it:
+<p>The function <code class="function"><a class="link" href="gobject-Type-Information.html#g-type-class-peek-parent" title="g_type_class_peek_parent ()">g_type_class_peek_parent</a></code>
+    is used to access the original parent class structure. Its input is a
+    pointer to the class of the derived object and it returns a pointer to
+    the original parent class structure. Instead of using this function
+    directly, though, you should use the <code class="function">parent_class</code>
+    pointer created and initialized for us by the G_DEFINE_TYPE_* family of
+    macros, for instance:
 </p>
 <pre class="programlisting">
 static void
 b_method_to_call (B *obj, int a)
 {
-  BClass *klass;
-  AClass *parent_class;
-  klass = B_GET_CLASS (obj);
-  parent_class = g_type_class_peek_parent (klass);
   /* do stuff before chain up */
-  parent_class-&gt;method_to_call (obj, a);
+  /* call the method_to_call() virtual function on the
+   * parent of BClass, AClass.
+   *
+   * remember the explicit cast to AClass*
+   */
+  A_CLASS (b_parent_class)-&gt;method_to_call (obj, a);
   /* do stuff after chain up */
 }
@@ -95,6 +93,6 @@ b_method_to_call (B *obj, int a)
 </div>
 <div class="footer">
 <hr>
-          Generated by GTK-Doc V1.18.1</div>
+          Generated by GTK-Doc V1.19</div>
 </body>
 </html>

data/vendor/local/share/gtk-doc/html/gobject/howto-gobject-code.html CHANGED Viewed

@@ -8,7 +8,7 @@
 <link rel="up" href="howto-gobject.html" title="How to define and implement a new GObject">
 <link rel="prev" href="howto-gobject.html" title="How to define and implement a new GObject">
 <link rel="next" href="howto-gobject-construction.html" title="Object Construction">
-<meta name="generator" content="GTK-Doc V1.18.1 (XML mode)">
+<meta name="generator" content="GTK-Doc V1.19 (XML mode)">
 <link rel="stylesheet" href="style.css" type="text/css">
 </head>
 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
@@ -67,7 +67,7 @@ struct _MamanBarPrivate {
 </p>
 <pre class="programlisting">
-G_DEFINE_TYPE (MamanBar, maman_bar, G_TYPE_OBJECT);
+G_DEFINE_TYPE (MamanBar, maman_bar, G_TYPE_OBJECT)
 </pre>
 <p>
     </p>
@@ -76,11 +76,13 @@ G_DEFINE_TYPE (MamanBar, maman_bar, G_TYPE_OBJECT);
       <code class="function">G_DEFINE_TYPE_WITH_CODE</code> macro to control the
       get_type function implementation - for instance, to add a call to
       <code class="function">G_IMPLEMENT_INTERFACE</code> macro which will
-      call the <code class="function">g_type_implement_interface</code> function.
+      call the <code class="function">g_type_implement_interface</code> function,
+      or call the <code class="function">G_ADD_PRIVATE</code> macro will add an
+      instance private data structure.
     </p>
 </div>
 <div class="footer">
 <hr>
-          Generated by GTK-Doc V1.18.1</div>
+          Generated by GTK-Doc V1.19</div>
 </body>
 </html>

data/vendor/local/share/gtk-doc/html/gobject/howto-gobject-construction.html CHANGED Viewed

@@ -8,7 +8,7 @@
 <link rel="up" href="howto-gobject.html" title="How to define and implement a new GObject">
 <link rel="prev" href="howto-gobject-code.html" title="Boilerplate code">
 <link rel="next" href="howto-gobject-destruction.html" title="Object Destruction">
-<meta name="generator" content="GTK-Doc V1.18.1 (XML mode)">
+<meta name="generator" content="GTK-Doc V1.19 (XML mode)">
 <link rel="stylesheet" href="style.css" type="text/css">
 </head>
 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
@@ -41,30 +41,37 @@
       No object reference will be returned to the client of <code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-new" title="g_object_new ()">g_object_new</a></code>
       until all the construction properties have been set.
     </p>
+<p>
+      It is important to note that object construction cannot <span class="emphasis"><em>ever</em></span>
+      fail. If you require a fallible GObject construction, you can use the
+      GInitable and GAsyncInitable interfaces provided by the GIO library
+    </p>
 <p>
       As such, I would recommend writing the following code first:
 </p>
 <pre class="programlisting">
+G_DEFINE_TYPE_WITH_PRIVATE (MamanBar, maman_bar, G_TYPE_OBJECT)
+static void
+maman_bar_class_init (MamanBarClass *klass)
+{
+}
 static void
 maman_bar_init (MamanBar *self)
 {
-  self-&gt;priv = MAMAN_BAR_GET_PRIVATE (self);
+  self-&gt;priv = maman_bar_get_instance_private (self);
   /* initialize all public and private members to reasonable default values. */
-  /* If you need specific construction properties to complete initialization,
-   * delay initialization completion until the property is set.
-   */
 }
 </pre>
 <p>
     </p>
 <p>
-      Now, if you need special construction properties, install the properties in the class_init function,
-      override the set and get methods and implement the get and set methods as described in
-      <a class="xref" href="gobject-properties.html" title="Object properties">the section called “Object properties”</a>. Make sure that these properties use a construct only
-      <a class="link" href="gobject-GParamSpec.html#GParamSpec" title="struct GParamSpec"><span class="type">GParamSpec</span></a> by setting the param spec's flag field to G_PARAM_CONSTRUCT_ONLY: this helps
-      GType ensure that these properties are not set again later by malicious user code.
+      If you need special construction properties, install the properties in
+      the <code class="function">class_init()</code> function, override the <code class="function">set_property()</code>
+      and <code class="function">get_property()</code> methods of the GObject class,
+      and implement them as described by <a class="xref" href="gobject-properties.html" title="Object properties">the section called “Object properties”</a>.
 </p>
 <div class="informalexample">
   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
@@ -98,7 +105,10 @@ maman_bar_init (MamanBar *self)
 26
 27
 28
-29</pre></td>
+29
+30
+31
+32</pre></td>
         <td class="listing_code"><pre class="programlisting"><span class="keyword">enum</span><span class="normal"> </span><span class="cbracket">{</span>
 <span class="normal">  PROP_0</span><span class="symbol">,</span>
@@ -107,6 +117,7 @@ maman_bar_init (MamanBar *self)
 <span class="normal">  N_PROPERTIES</span>
 <span class="cbracket">}</span><span class="symbol">;</span>
+<span class="comment">/* Keep a pointer to the properties definition */</span>
 <span class="keyword">static</span><span class="normal"> </span><span class="usertype">GParamSpec</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">obj_properties</span><span class="symbol">[</span><span class="normal">N_PROPERTIES</span><span class="symbol">]</span><span class="normal"> </span><span class="symbol">=</span><span class="normal"> </span><span class="cbracket">{</span><span class="normal"> <a href="../glib/glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">,</span><span class="normal"> </span><span class="cbracket">}</span><span class="symbol">;</span>
 <span class="keyword">static</span><span class="normal"> </span><span class="type">void</span>
@@ -122,7 +133,9 @@ maman_bar_init (MamanBar *self)
 <span class="normal">                         </span><span class="string">"Maman construct prop"</span><span class="symbol">,</span>
 <span class="normal">                         </span><span class="string">"Set maman's name"</span><span class="symbol">,</span>
 <span class="normal">                         </span><span class="string">"no-name-set"</span><span class="normal"> </span><span class="comment">/* default value */</span><span class="symbol">,</span>
-<span class="normal">                         <a href="gobject-GParamSpec.html#G-PARAM-CONSTRUCT-ONLY:CAPS">G_PARAM_CONSTRUCT_ONLY</a> </span><span class="symbol">|</span><span class="normal"> <a href="gobject-GParamSpec.html#G-PARAM-READWRITE:CAPS">G_PARAM_READWRITE</a></span><span class="symbol">);</span>
+<span class="normal">                         <a href="gobject-GParamSpec.html#G-PARAM-CONSTRUCT-ONLY:CAPS">G_PARAM_CONSTRUCT_ONLY</a> </span><span class="symbol">|</span>
+<span class="normal">                         <a href="gobject-GParamSpec.html#G-PARAM-READWRITE:CAPS">G_PARAM_READWRITE</a> </span><span class="symbol">|</span>
+<span class="normal">                         <a href="gobject-GParamSpec.html#G-PARAM-STATIC-STRINGS:CAPS">G_PARAM_STATIC_STRINGS</a></span><span class="symbol">);</span>
 <span class="normal">  </span><span class="function"><a href="gobject-The-Base-Object-Type.html#g-object-class-install-properties">g_object_class_install_properties</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">gobject_class</span><span class="symbol">,</span>
 <span class="normal">                                     N_PROPERTIES</span><span class="symbol">,</span>
@@ -134,27 +147,25 @@ maman_bar_init (MamanBar *self)
 </div>
 <p>
-      If you need this, make sure you can build and run code similar to the code shown above. Make sure
-      your construct properties can set correctly during construction, make sure you cannot set them
-      afterwards and make sure that if your users do not call <code class="function"><a class="link" href="gobject-The-Base-Object-Type.html#g-object-new" title="g_object_new ()">g_object_new</a></code>
-      with the required construction properties, these will be initialized with the default values.
-    </p>
-<p>
-      I consider good taste to halt program execution if a construction property is set its
-      default value. This allows you to catch client code which does not give a reasonable
-      value to the construction properties. Of course, you are free to disagree but you
-      should have a good reason to do so.
+      If you need this, make sure you can build and run code similar to the
+      code shown above. Also, make sure your construct properties can be set
+      without side effects during construction.
     </p>
 <p>
-      Some people sometimes need to construct their object but only after
-      the construction properties have been set. This is possible through
-      the use of the constructor class method as described in
-      <a class="xref" href="chapter-gobject.html#gobject-instantiation" title="Object instantiation">the section called “Object instantiation”</a> or, more simply, using
-      the constructed class method available since GLib 2.12.
+      Some people sometimes need to complete the initialization of a instance
+      of a type only after the properties passed to the constructors have been
+      set. This is possible through the use of the <code class="function">constructor()</code>
+      class method as described in <a class="xref" href="chapter-gobject.html#gobject-instantiation" title="Object instantiation">the section called “Object instantiation”</a> or,
+      more simply, using the <code class="function">constructed()</code> class method
+      available since GLib 2.12. Note that the <code class="function">constructed()</code>
+      virtual function will only be invoked after the properties marked as
+      G_PARAM_CONSTRUCT_ONLY or G_PARAM_CONSTRUCT have been consumed, but
+      before the regular properties passed to <code class="function">g_object_new()</code>
+      have been set.
     </p>
 </div>
 <div class="footer">
 <hr>
-          Generated by GTK-Doc V1.18.1</div>
+          Generated by GTK-Doc V1.19</div>
 </body>
 </html>

data/vendor/local/share/gtk-doc/html/gobject/howto-gobject-destruction.html CHANGED Viewed

@@ -8,7 +8,7 @@
 <link rel="up" href="howto-gobject.html" title="How to define and implement a new GObject">
 <link rel="prev" href="howto-gobject-construction.html" title="Object Construction">
 <link rel="next" href="howto-gobject-methods.html" title="Object methods">
-<meta name="generator" content="GTK-Doc V1.18.1 (XML mode)">
+<meta name="generator" content="GTK-Doc V1.19 (XML mode)">
 <link rel="stylesheet" href="style.css" type="text/css">
 </head>
 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
@@ -31,11 +31,12 @@
     </p>
 <p>
       The destruction process of your object might be split in two different
-      phases: dispose and the finalize.
+      phases: dispose and the finalize. This split is necessary to handle
+      potential cycles due to the nature of the reference counting mechanism
+      used by GObject, as well as dealing with temporary vivification of
+      instances in case of signal emission during the destruction sequence.
 </p>
 <pre class="programlisting">
-#define MAMAN_BAR_GET_PRIVATE(obj) (G_TYPE_INSTANCE_GET_PRIVATE ((obj), MAMAN_TYPE_BAR, MamanBarPrivate))
 struct _MamanBarPrivate
 {
   GObject *an_object;
@@ -43,31 +44,29 @@ struct _MamanBarPrivate
   gchar *a_string;
 };
-G_DEFINE_TYPE (MamanBar, maman_bar, G_TYPE_OBJECT);
+G_DEFINE_TYPE_WITH_PRIVATE (MamanBar, maman_bar, G_TYPE_OBJECT)
 static void
 maman_bar_dispose (GObject *gobject)
 {
   MamanBar *self = MAMAN_BAR (gobject);
-  /*
-   * In dispose, you are supposed to free all types referenced from this
+  /* In dispose(), you are supposed to free all types referenced from this
    * object which might themselves hold a reference to self. Generally,
    * the most simple solution is to unref all members on which you own a
    * reference.
    */
-  /* dispose might be called multiple times, so we must guard against
-   * calling g_object_unref() on an invalid GObject.
+  /* dispose() might be called multiple times, so we must guard against
+   * calling g_object_unref() on an invalid GObject by setting the member
+   * NULL; g_clear_object() does this for us, atomically.
    */
-  if (self-&gt;priv-&gt;an_object)
-    {
-      g_object_unref (self-&gt;priv-&gt;an_object);
-      self-&gt;priv-&gt;an_object = NULL;
-    }
+  g_clear_object (&amp;self-&gt;priv-&gt;an_object);
-  /* Chain up to the parent class */
+  /* Always chain up to the parent class; there is no need to check if
+   * the parent class implements the dispose() virtual function: it is
+   * always guaranteed to do so
+   */
   G_OBJECT_CLASS (maman_bar_parent_class)-&gt;dispose (gobject);
 }
@@ -78,7 +77,9 @@ maman_bar_finalize (GObject *gobject)
   g_free (self-&gt;priv-&gt;a_string);
-  /* Chain up to the parent class */
+  /* Always chain up to the parent class; as with dispose(), finalize()
+   * is guaranteed to exist on the parent's class virtual function table
+   */
   G_OBJECT_CLASS (maman_bar_parent_class)-&gt;finalize (gobject);
 }
@@ -89,14 +90,12 @@ maman_bar_class_init (MamanBarClass *klass)
   gobject_class-&gt;dispose = maman_bar_dispose;
   gobject_class-&gt;finalize = maman_bar_finalize;
-  g_type_class_add_private (klass, sizeof (MamanBarPrivate));
 }
 static void
 maman_bar_init (MamanBar *self);
 {
-  self-&gt;priv = MAMAN_BAR_GET_PRIVATE (self);
+  self-&gt;priv = maman_bar_get_instance_private (self);
   self-&gt;priv-&gt;an_object = g_object_new (MAMAN_TYPE_BAZ, NULL);
   self-&gt;priv-&gt;a_string = g_strdup ("Maman");
@@ -104,19 +103,15 @@ maman_bar_init (MamanBar *self);
 </pre>
 <p>
     </p>
-<p>
-      Add similar code to your GObject, make sure the code still builds
-      and runs: dispose and finalize must be called during the last unref.
-    </p>
 <p>
       It is possible that object methods might be invoked after dispose is
       run and before finalize runs. GObject does not consider this to be a
       program error: you must gracefully detect this and neither crash nor
-      warn the user.
+      warn the user, by having a disposed instance revert to an inhert state.
     </p>
 </div>
 <div class="footer">
 <hr>
-          Generated by GTK-Doc V1.18.1</div>
+          Generated by GTK-Doc V1.19</div>
 </body>
 </html>

data/vendor/local/share/gtk-doc/html/gobject/howto-gobject-methods.html CHANGED Viewed

@@ -8,7 +8,7 @@
 <link rel="up" href="howto-gobject.html" title="How to define and implement a new GObject">
 <link rel="prev" href="howto-gobject-destruction.html" title="Object Destruction">
 <link rel="next" href="howto-gobject-chainup.html" title="Chaining up">
-<meta name="generator" content="GTK-Doc V1.18.1 (XML mode)">
+<meta name="generator" content="GTK-Doc V1.19 (XML mode)">
 <link rel="stylesheet" href="style.css" type="text/css">
 </head>
 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
@@ -25,7 +25,7 @@
 <p>
       Just as with C++, there are many different ways to define object
       methods and extend them: the following list and sections draw on
-      C++ vocabulary. (Readers are expected to know basic C++ buzzwords.
+      C++ vocabulary. (Readers are expected to know basic C++ concepts.
       Those who have not had to write C++ code recently can refer to e.g.
       <a class="ulink" href="http://www.cplusplus.com/doc/tutorial/" target="_top">http://www.cplusplus.com/doc/tutorial/</a> to refresh
       their memories.)
@@ -67,7 +67,6 @@ maman_bar_do_action (MamanBar *self, /* parameters */)
 </pre>
 <p>
       </p>
-<p>There is really nothing scary about this.</p>
 </div>
 <div class="sect2">
 <div class="titlepage"><div><div><h3 class="title">
@@ -102,34 +101,15 @@ maman_bar_do_action (MamanBar *self, /* parameters */)
 </pre>
 <p>
         The code above simply redirects the do_action call to the relevant
-        class function. Some users, concerned about performance, do not
-        provide the <code class="function">maman_bar_do_action</code> wrapper function
-        and require users to dereference the class pointer themselves. This
-        is not such a great idea in terms of encapsulation and makes it
-        difficult to change the object's implementation afterwards, should
-        this be needed.
-      </p>
-<p>
-        Other users, also concerned by performance issues, declare
-        the <code class="function">maman_bar_do_action</code> function inline in the
-        header file. This, however, makes it difficult to change the
-        object's implementation later (although easier than requiring users
-        to directly dereference the class function) and is often difficult
-        to write in a portable way (the <span class="emphasis"><em>inline</em></span> keyword
-        is part of the C99 standard but not every compiler supports it).
-      </p>
-<p>
-        In doubt, unless a user shows you hard numbers about the performance
-        cost of the function call, just implement <code class="function">maman_bar_do_action</code>
-        in the source file.
+        class function.
       </p>
 <p>
         Please, note that it is possible for you to provide a default
         implementation for this class method in the object's
         <code class="function">class_init</code> function: initialize the
         klass-&gt;do_action field to a pointer to the actual implementation.
-        You can also make this class method pure virtual by initializing
-        the klass-&gt;do_action field to NULL:
+        By default, class method that are not inherited are initialized to
+        NULL, and thus are to be considered "pure virtual".
 </p>
 <pre class="programlisting">
 static void
@@ -141,7 +121,10 @@ maman_bar_real_do_action_two (MamanBar *self, /* parameters */)
 static void
 maman_bar_class_init (BarClass *klass)
 {
-  /* pure virtual method: mandates implementation in children. */
+  /* this is not necessary, except for demonstration purposes.
+   *
+   * pure virtual method: mandates implementation in children.
+   */
   klass-&gt;do_action_one = NULL;
   /* merely virtual method. */
@@ -153,7 +136,17 @@ maman_bar_do_action_one (MamanBar *self, /* parameters */)
 {
   g_return_if_fail (MAMAN_IS_BAR (self));
-  MAMAN_BAR_GET_CLASS (self)-&gt;do_action_one (self, /* parameters */);
+  /* if the method is purely virtual, then it is a good idea to
+   * check that it has been overridden before calling it, and,
+   * depending on the intent of the class, either ignore it silently
+   * or warn the user.
+   /
+  if (MAMAN_BAR_GET_CLASS (self)-&gt;do_action_one != NULL)
+    MAMAN_BAR_GET_CLASS (self)-&gt;do_action_one (self, /* parameters */);
+  else
+    g_warning ("Class '%s' does not override the mandatory "
+               "MamanBarClass.do_action_one() virtual function.",
+               G_OBJECT_TYPE_NAME (self));
 }
 void
@@ -252,6 +245,6 @@ maman_bar_subtype_class_init (MamanBarSubTypeClass *klass)
 </div>
 <div class="footer">
 <hr>
-          Generated by GTK-Doc V1.18.1</div>
+          Generated by GTK-Doc V1.19</div>
 </body>
 </html>