diff -r 1687adb2b7f0 -r fba31e9504a1 samples/exceptions/src/org/apidesign/exceptions/trycatchredo/UserQuestionException.java
--- a/samples/exceptions/src/org/apidesign/exceptions/trycatchredo/UserQuestionException.java	Sun Feb 01 13:38:08 2009 +0100
+++ b/samples/exceptions/src/org/apidesign/exceptions/trycatchredo/UserQuestionException.java	Sun Feb 01 16:03:37 2009 +0100
@@ -3,11 +3,27 @@
 import java.io.IOException;
 import javax.swing.JOptionPane;
 
-/**
+/** Specialized I/O exception to request some kind of user confirmation.
+ * A code that needs to ask user shall not attempt to open a dialog itself,
+ * rather it shall emit this exception and let its callers show the dialog
+ * at appropriate time.
  *
  * @author Jaroslav Tulach
+ * @since 2.0
  */
 public abstract class UserQuestionException extends IOException {
+    /** Description of the dialog to show to the user. Whoever catches
+     * this exception shall use {@link #getQuestionPane()}.{@link JOptionPane#createDialog(java.lang.String)}
+     * to construct and display the dialog.
+     * 
+     * @return the pane to display to user
+     */
     public abstract JOptionPane getQuestionPane();
+    /** When the user confirms (or rejects) message presented by the
+     * {@link #getQuestionPane()} dialog, the exception shall be notified
+     * by calling this method with {@link JOptionPane#getValue()} option.
+     *
+     * @param option the option selected by the user
+     */
     public abstract void confirm(Object option);
 }