diff --git a/src/calibre/gui2/dialogs/message_box.py b/src/calibre/gui2/dialogs/message_box.py
index 64c8bf75ba..e15cd055b9 100644
--- a/src/calibre/gui2/dialogs/message_box.py
+++ b/src/calibre/gui2/dialogs/message_box.py
@@ -158,6 +158,13 @@ _proceed_memory = []
 
 class ProceedNotification(MessageBox): # {{{
 
+    '''
+    WARNING: This class is deprecated. DO not use it as some users ahve
+    reported crashes when closing the dialog box generated by this class.
+    Instead use: gui.proceed_question(...) The arguments are the same as for
+    this class.
+    '''
+
     def __init__(self, callback, payload, html_log, log_viewer_title, title, msg,
             det_msg='', show_copy_button=False, parent=None,
             cancel_callback=None, log_is_file=False):
diff --git a/src/calibre/gui2/proceed.py b/src/calibre/gui2/proceed.py
index 433b365e35..422e1c0e0f 100644
--- a/src/calibre/gui2/proceed.py
+++ b/src/calibre/gui2/proceed.py
@@ -129,6 +129,25 @@ class ProceedQuestion(QDialog):
     def __call__(self, callback, payload, html_log, log_viewer_title, title,
             msg, det_msg='', show_copy_button=False, cancel_callback=None,
             log_is_file=False):
+        '''
+        A non modal popup that notifies the user that a background task has
+        been completed. This class guarantees that onlya single popup is
+        visible at any one time. Other requests are queued and displayed after
+        the user dismisses the current popup.
+
+        :param callback: A callable that is called with payload if the user
+        asks to proceed. Note that this is always called in the GUI thread.
+        :param cancel_callback: A callable that is called with the payload if
+        the users asks not to proceed.
+        :param payload: Arbitrary object, passed to callback
+        :param html_log: An HTML or plain text log
+        :param log_viewer_title: The title for the log viewer window
+        :param title: The title for this popup
+        :param msg: The msg to display
+        :param det_msg: Detailed message
+        :param log_is_file: If True the html_log parameter is interpreted as
+        the path to a file on disk containing the log encoded with utf-8
+        '''
         question = Question(payload, callback, cancel_callback, title, msg,
                 html_log, log_viewer_title, log_is_file, det_msg,
                 show_copy_button)