Document safety requirements for __private functions

The previous "See underlying function" text didn't provide a way to
find the underlying function, forcing users to search the codebase.
Stating the safety contracts explicitly makes the API usable.

nix-bindings-expr/src/value/__private.rs

@@ -2,20 +2,25 @@
 use super::Value;
 use nix_bindings_bindgen_raw as raw;
 
-/// See [Value::new].
+/// Take ownership of a new [`Value`].
+///
+/// This does not call `nix_gc_incref`, but does call `nix_gc_decref` when dropped.
 ///
 /// # Safety
 ///
-/// See underlying function.
+/// The caller must ensure that the provided `ptr` has a positive reference count,
+/// and that `ptr` is not used after the returned `Value` is dropped.
 pub unsafe fn raw_value_new(ptr: *mut raw::Value) -> Value {
     Value::new(ptr)
 }
 
-/// See [Value::new_borrowed].
+/// Borrow a reference to a [`Value`].
+///
+/// This calls `value_incref`, and the returned Value will call `value_decref` when dropped.
 ///
 /// # Safety
 ///
-/// See underlying function.
+/// The caller must ensure that the provided `ptr` has a positive reference count.
 pub unsafe fn raw_value_new_borrowed(ptr: *mut raw::Value) -> Value {
     Value::new_borrowed(ptr)
 }