Some small documentation improvements

Make it a bit clearer that the registry is the solution for most lifetime issues
when using rlua.

Author: kyren

src/context.rs

@@ -429,6 +429,15 @@ impl<'lua> Context<'lua> {
     ///
     /// This value will be available to rust from all `Lua` instances which share the same main
     /// state.
+    ///
+    /// The returned [`RegistryKey`] is of `'static` lifetime and is *the* main way in `rlua` of
+    /// maintaining ownership of a Lua value outside of a [`Lua::context`] call.
+    ///
+    /// Be warned, garbage collection of values held inside the registry is not automatic, see
+    /// [`RegistryKey`] for more details.
+    ///
+    /// [`RegistryKey`]: struct.RegistryKey.html
+    /// [`Lua::context`]: struct.Lua.html#method.context
     pub fn create_registry_value<T: ToLua<'lua>>(self, t: T) -> Result<RegistryKey> {
         let t = t.to_lua(self)?;
         unsafe {

src/types.rs

@@ -30,16 +30,20 @@ pub(crate) type Callback<'lua, 'a> =
 /// [`Context::remove_registry_value`], and instances not manually removed can be garbage collected
 /// with [`Context::expire_registry_values`].
 ///
-/// Be warned, If you place this into Lua via a `UserData` type or a rust callback, it is *very
-/// easy* to accidentally cause reference cycles that the Lua garbage collector cannot resolve.
-/// Instead of placing a `RegistryKey` into a `UserData` type, prefer instead to use
-/// [`UserData::set_user_value`] / [`UserData::get_user_value`], and instead of moving a RegistryKey
-/// into a callback, prefer [`Context::scope`].
+/// Be warned, If you place this into Lua via a `UserData` type or a rust callback and rely on
+/// [`Context::expire_registry_values`], it is *very easy* to accidentally cause reference cycles
+/// that cannot be automatically collected.  The Lua garbage collector is not aware of the registry
+/// handle pattern, so holding onto a `RegistryKey` inside Lua may lead to it never being dropped,
+/// and it if it is not droped, [`Context::expire_registry_values`] will never remove the value from
+/// the registry, leading to an uncollectable cycle.  Instead of placing a `RegistryKey` into Lua
+/// and relying on it being automatically dropped, prefer APIs which the Lua garbage collector
+/// understands, such as [`UserData::set_user_value`] / [`UserData::get_user_value`] for UserData
+/// types and [`Function::bind`] for callbacks.
 ///
 /// [`Context::registry_value`]: struct.Context.html#method.registry_value
 /// [`Context::remove_registry_value`]: struct.Context.html#method.remove_registry_value
 /// [`Context::expire_registry_values`]: struct.Context.html#method.expire_registry_values
-/// [`Context::scope`]: struct.Context.html#method.scope
+/// [`Function::bind`]: struct.Function.html#method.bind
 /// [`UserData::set_user_value`]: struct.UserData.html#method.set_user_value
 /// [`UserData::get_user_value`]: struct.UserData.html#method.get_user_value
 pub struct RegistryKey {