Bug 329563 r=annie.sullivan Clarify annotation IDL documentation

browser/components/places/public/nsIAnnotationService.idl

@@ -99,14 +99,25 @@ interface nsIAnnotationService : nsISupports
      * "bills_extension/page_state" or "history/thumbnail".
      *
      * Do not use characters that are not valid in URLs such as spaces, ":",
-     * or many other symbols.
+     * commas, or most other symbols. You should stick to ASCII letters and
+     * numbers plus "_", "-", and "/".
      *
      * aExpiration is one of EXPIRE_* above. aFlags should be 0 for now, some
      * flags will be defined in the future.
      *
+     * NOTE: ALL ANNOTATIONS WILL GET DELETED WHEN THE PAGE IS REMOVED FROM
+     * HISTORY, regardless of expiration date. This means that if you create an
+     * annotation on a random unvisited URI, it will get deleted when the
+     * browser shuts down.  Otherwise, things can exist in history as
+     * annotations but the user has no way of knowing it, potentially violating
+     * their privacy expectations about actions such as "Clear history." If
+     * there is an important annotation that the user wants to keep, you should
+     * make sure that URL is bookmarked. This will ensure the item is never
+     * completely deleted from the history database.
+     *
      * The annotation "favicon" is special. favicons are stored in the favicon
      * service, but are special cased in the protocol handler so they look like
-     * annotations. Do not set favicons using this service.
+     * annotations. Do not set favicons using this service, it will not work.
      */
     void setAnnotationString(in nsIURI aURI, in AUTF8String aName,
                              in AString aValue, in PRInt32 aFlags,