gobject: reword documentation for GWeakNotify

gobject/gobject.h

@@ -233,18 +233,17 @@ typedef void (*GObjectFinalizeFunc)     (GObject      *object);
  * GWeakNotify:
  * @data: data that was provided when the weak reference was established
  * @where_the_object_was: the object being disposed
- * 
+ *
  * A #GWeakNotify function can be added to an object as a callback that gets
- * triggered when the object is finalized.
+ * triggered before an object is disposed.
  *
- * Since the object is already being disposed when the #GWeakNotify is called,
- * there's not much you could do with the object, apart from e.g. using its
- * address as hash-index or the like.
+ * At that time, the object is still mostly alive and well, so new references
+ * or weak notifications can be taken. Such resurrection is however discouraged.
  *
- * In particular, this means it’s invalid to call g_object_ref(),
- * g_weak_ref_init(), g_weak_ref_set(), g_object_add_toggle_ref(),
- * g_object_weak_ref(), g_object_add_weak_pointer() or any function which calls
- * them on the object from this callback.
+ * Also, if a weak notification is added during dipose, it will be emitted
+ * right before finalize. At that time, the reference count of the object already
+ * dropped to zero and taking another reference or registering new weak references
+ * is forbidden.
  */
 typedef void (*GWeakNotify)		(gpointer      data,
 					 GObject      *where_the_object_was);