Recommend the usage of the with statement for freeze_notify and handl…

…er_block

source/objects.txt

@@ -249,10 +249,46 @@ API
         emitted when any property is changed) until the :meth:`thaw_notify` method is
         called.
 
+        It recommended to use the *with* statement when calling :meth:`freeze_notify`,
+        that way it is ensured that :meth:`that_notify` is called implicitly at
+        the end of the block::
+
+            with an_object.freeze_notify():
+                # Do your work here
+                ...
+
     .. method:: thaw_notify()
 
         Thaw all the "notify::" signals which were thawed by :meth:`freeze_notify`.
 
+        It is recommended to not call :meth:`thaw_notify` explicitly but use
+        :meth:`freeze_notify` together with the *with* statement.
+
+    .. method:: handler_block(handler_id)
+
+        Blocks a handler of an instance so it will not be called during any signal
+        emissions unless :meth:`handler_unblock` is called for that *handler_id*.
+        Thus "blocking" a signal handler means to temporarily deactivate it, a
+        signal handler has to be unblocked exactly the same amount of times it
+        has been blocked before to become active again.
+
+        It is recommended to use :meth:`handler_block` in conjunction with the
+        *with* statement which will call :meth:`handler_unblock` implicitly at
+        the end of the block::
+
+            with an_object.handler_block(handler_id):
+                # Do your work here
+                ...
+
+    .. method:: handler_unblock(handler_id)
+
+        Undoes the effect of :meth:`handler_block`. A blocked handler is skipped
+        during signal emissions and will not be invoked until it has been unblocked
+        exactly the amount of times it has been blocked before.
+
+        It is recommended to not call :meth:`handler_unblock` explicitly but use
+        :meth:`handler_block` together with the *with* statement.
+
     .. attribute:: __gsignals__
 
         A dictionary where inherited class can define new signals.