[libwnck] doc: Finish wnck_shutdown()-related docs, with note about introspection

[Vincent Untz <vuntz src gnome org>]

commit 500561512c2b073072206aa70e28590fb04e65bb
Author: Vincent Untz <vuntz gnome org>
Date:   Mon Jan 30 14:58:38 2012 +0100

    doc: Finish wnck_shutdown()-related docs, with note about introspection
    
    The introspection note is quite important, as the way memory management
    works in libwnck is not completely compatible with introspection. And
    wnck_shutdown() exhibits this.
    
    See https://bugzilla.gnome.org/show_bug.cgi?id=642692#c11 for
    discussion.

 doc/libwnck-docs.sgml    |   21 ++++++++++++++++++++-
 doc/libwnck-sections.txt |    1 +
 doc/tmpl/misc.sgml       |    8 ++++++++
 libwnck/util.c           |   17 ++++++++++++-----
 4 files changed, 41 insertions(+), 6 deletions(-)
---
diff --git a/doc/libwnck-docs.sgml b/doc/libwnck-docs.sgml
index daf1c50..911940b 100644
--- a/doc/libwnck-docs.sgml
+++ b/doc/libwnck-docs.sgml
@@ -45,7 +45,7 @@
     </para>
 
     <para>
-     Applications that just need to do some management on their own windows (like positioning one of their windows on a specific workspace) should likely not use libwnck, as the use of this library is relatively expensive in terms of resources. The internals of libwnck make sure that the library always tracks everything that is occurring on the display, mirroring various information from the X server and actively using resources to update the cached information as it changes. In concrete termes, every time something changes on the display, every application using libwnck will wake up. An application that is not dealing specifically with window management should not do this.
+     Applications that just need to do some management on their own windows (like positioning one of their windows on a specific workspace) should likely not use libwnck, as the use of this library is relatively expensive in terms of resources. The internals of libwnck make sure that the library always tracks everything that is occurring on the display, mirroring various information from the X server and actively using resources to update the cached information as it changes. In concrete terms, every time something changes on the display, every application using libwnck will wake up. An application that is not dealing specifically with window management should not do this. While <link linkend="wnck-shutdown"><function>wnck_shutdown()</function></link> can be used to mitigate the expensiveness of libwnck, it is generally not considered a proper solution.
     </para>
 
     <note><simpara>
@@ -78,6 +78,22 @@
      <para>
       All objects provided by the <link linkend="core">Core Window Management Support</link> are owned by libwnck and should not be referenced or unreferenced by the user. Those objects are tied to X resources, and it makes no sense to keep the objects alive when the X resources are gone; doing so could lead to errors. Therefore it is important that, when keeping in memory a pointer to such an object, the life of this object is tracked to make sure the pointer is always valid.
      </para>
+     <para>
+      This memory management model is important to keep in mind for users of <link linkend="wnck-shutdown"><function>wnck_shutdown()</function></link>, and especially for users of libwnck through introspection. With introspection, all variables pointing to objects owned by libwnck must be cleared before <link linkend="wnck-shutdown"><function>wnck_shutdown()</function></link> as the introspection support can add some references to the objects.
+     </para>
+     <para>
+      For instance, the following would work in Python:
+      <informalexample>
+       <programlisting language="python">
+from gi.repository import Wnck
+
+screen = Wnck.Screen.get_default()
+[...]
+screen = None
+Wnck.Shutdown()
+       </programlisting>
+      </informalexample>
+     </para>
     </sect2>
 
     <sect2 id="getting-started.pitfalls.client-type">
@@ -187,6 +203,9 @@
     <index role="3.0">
       <title>Index of new symbols in 3.0</title>
     </index> 
+    <index role="3.4">
+      <title>Index of new symbols in 3.4</title>
+    </index>
   </part>
   <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
 </book>
diff --git a/doc/libwnck-sections.txt b/doc/libwnck-sections.txt
index 8e93d6e..39c69da 100644
--- a/doc/libwnck-sections.txt
+++ b/doc/libwnck-sections.txt
@@ -337,6 +337,7 @@ wnck_pid_read_resource_usage
 <TITLE>Miscellaneous Functions</TITLE>
 WnckClientType
 wnck_set_client_type
+wnck_shutdown
 </SECTION>
 
 <SECTION>
diff --git a/doc/tmpl/misc.sgml b/doc/tmpl/misc.sgml
index 6fbc3cf..223590e 100644
--- a/doc/tmpl/misc.sgml
+++ b/doc/tmpl/misc.sgml
@@ -36,3 +36,11 @@ Miscellaneous Functions
 @ewmh_sourceindication_client_type: 
 
 
+<!-- ##### FUNCTION wnck_shutdown ##### -->
+<para>
+
+</para>
+
+ void: 
+
+
diff --git a/libwnck/util.c b/libwnck/util.c
index 6416863..2926fef 100644
--- a/libwnck/util.c
+++ b/libwnck/util.c
@@ -789,11 +789,18 @@ _wnck_stock_icons_init (void)
 /**
  * wnck_shutdown:
  *
- * Stop listening to events and tear down all resources from libwnck. This
- * should be done if you are not going to need the state change notifications
- * for an extended period of time, to avoid wakeups with every key and focus
- * event. After this all Wnck object references you might still hold are
- * invalid.
+ * Makes libwnck stop listening to events and tear down all resources from
+ * libwnck. This should be done if you are not going to need the state change
+ * notifications for an extended period of time, to avoid wakeups with every
+ * key and focus event.
+ *
+ * After this, all pointers to Wnck object you might still hold are invalid.
+ *
+ * Due to the fact that <link
+ * linkend="getting-started.pitfalls.memory-management">Wnck objects are all
+ * owned by libwnck</link>, users of this API through introspection should be
+ * extremely careful: they must explicitly clear variables referencing objects
+ * before this call. Failure to do so might result in crashes.
  *
  * Since: 3.4
  */