From 278a1379e2c9812446f71eb812f44e5d1e95f9f0 Mon Sep 17 00:00:00 2001 From: Robert Hensing Date: Tue, 16 Dec 2025 02:05:44 +0100 Subject: [PATCH] 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 | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/nix-bindings-expr/src/value/__private.rs b/nix-bindings-expr/src/value/__private.rs index 558bcbc..84151e1 100644 --- a/nix-bindings-expr/src/value/__private.rs +++ b/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) }