freezing interface for embedding. r=chak/sr=alecf. bug#99623

webshell/public/nsIClipboardCommands.idl

@@ -23,7 +23,12 @@
 #include "nsISupports.idl"
 
 /**
- * @status UNDER_REVIEW
+ * An interface for embedding clients who wish to interact with
+ * the system-wide OS clipboard. Mozilla does not use a private
+ * clipboard, instead it places its data directly onto the system 
+ * clipboard. The webshell implements this interface.
+ *
+ * @status FROZEN
  */
 
 [scriptable, uuid(b8100c90-73be-11d2-92a5-00105a1b0d64)]
@@ -31,32 +36,51 @@ interface nsIClipboardCommands : nsISupports {
 
   /**
    * Returns whether there is a selection and it is not read-only.
+   *
+   * @return <code>true</code> if the current selection can be cut,
+   *          <code>false</code> otherwise.
    */
   boolean canCutSelection();
 
   /**
    * Returns whether there is a selection and it is copyable.
+   *
+   * @return <code>true</code> if there is a selection,
+   *          <code>false</code> otherwise.
    */
   boolean canCopySelection();
 
   /**
    * Returns whether we can copy a link location.
+   *
+   * @return <code>true</code> if a link is selected,
+   *           <code>false</code> otherwise.
    */
   boolean canCopyLinkLocation();
 
   /**
    * Returns whether we can copy an image location.
+   *
+   * @return <code>true</code> if an image is selected,
+              <code>false</code> otherwise.
    */
   boolean canCopyImageLocation();
 
   /**
    * Returns whether we can copy an image's contents.
+   *
+   * @return <code>true</code> if an image is selected,
+   *          <code>false</code> otherwise
    */
   boolean canCopyImageContents();
 
   /**
    * Returns whether the current contents of the clipboard can be
    * pasted and if the current selection is not read-only.
+   *
+   * @return <code>true</code> there is data to paste on the clipboard
+   *          and the current selection is not read-only,
+   *          <code>false</code> otherwise
    */
   boolean canPaste();