add doc for va_list APIs

Author: DiuDiu777

library/core/src/ffi/va_list.rs

@@ -243,10 +243,11 @@ impl<'f> VaListImpl<'f> {
     ///
     /// # Safety
     ///
-    /// This function is only sound to call when the next variable argument:
+    /// This function is only sound to call when:
     ///
-    /// - has a type that is ABI-compatible with the type `T`
-    /// - has a value that is a properly initialized value of type `T`
+    /// - there is a next variable argument available (i.e., the number of arguments already read from `ap` is less than the total number passed)
+    /// - the next variable argument has a type that is ABI-compatible with the type `T`
+    /// - the next variable argument has a value that is a properly initialized value of type `T`
     ///
     /// Calling this function with an incompatible type, an invalid value, or when there
     /// are no more variable arguments, is unsound.

library/core/src/intrinsics/mod.rs

@@ -3295,22 +3295,43 @@ pub(crate) const fn miri_promise_symbolic_alignment(ptr: *const (), align: usize
 
 /// Copies the current location of arglist `src` to the arglist `dst`.
 ///
-/// FIXME: document safety requirements
+/// # Safety
+///
+/// You must check the following invariants before you call this function:
+///
+/// - `dest` must be non-null and point to valid, writable memory.
+/// - `dest` must not alias `src`;
+///
 #[rustc_intrinsic]
 #[rustc_nounwind]
 pub unsafe fn va_copy<'f>(dest: *mut VaListImpl<'f>, src: &VaListImpl<'f>);
 
 /// Loads an argument of type `T` from the `va_list` `ap` and increment the
 /// argument `ap` points to.
 ///
-/// FIXME: document safety requirements
+/// # Safety
+///
+/// This function is only sound to call when:
+///
+/// - there is a next variable argument available (i.e., the number of arguments already read from `ap` is less than the total number passed)
+/// - the next variable argument has a type that is ABI-compatible with the type `T`
+/// - the next variable argument has a value that is a properly initialized value of type `T`
+///
+/// Calling this function with an incompatible type, an invalid value, or when there
+/// are no more variable arguments, is unsound.
+///
 #[rustc_intrinsic]
 #[rustc_nounwind]
 pub unsafe fn va_arg<T: VaArgSafe>(ap: &mut VaListImpl<'_>) -> T;
 
 /// Destroy the arglist `ap` after initialization with `va_start` or `va_copy`.
 ///
-/// FIXME: document safety requirements
+/// # Safety
+///
+/// You must check the following invariants before you call this function:
+///
+/// - `ap` must not be used to access variable arguments after this call
+///
 #[rustc_intrinsic]
 #[rustc_nounwind]
 pub unsafe fn va_end(ap: &mut VaListImpl<'_>);