update rustdocs for frozen

Author: mark-i-m

src/librustc_data_structures/frozen.rs

@@ -1,4 +1,4 @@
-//! An immutable, owned value.
+//! An immutable, owned value (except for interior mutability).
 //!
 //! The purpose of `Frozen` is to make a value immutable for the sake of defensive programming. For example,
 //! suppose we have the following:
@@ -37,6 +37,12 @@
 //! `Frozen` impls `Deref`, so we can ergonomically call methods on `Bar`, but it doesn't `impl
 //! DerefMut`.  Now calling `foo.compute.mutate()` will result in a compile-time error stating that
 //! `mutate` requires a mutable reference but we don't have one.
+//!
+//! # Caveats
+//!
+//! - `Frozen` doesn't try to defend against interior mutability (e.g. `Frozen<RefCell<Bar>>`).
+//! - `Frozen` doesn't pin it's contents (e.g. one could still do `foo.computed =
+//!    Frozen::freeze(new_bar)`).
 
 /// An owned immutable value.
 #[derive(Debug)]