Rollup merge of rust-lang#146925 - DiuDiu777:va-doc-fix, r=tgross35

Add doc for va_list APIs

I observed that [PR146521](rust-lang#146521) submitted two weeks ago resolved some documentation issues related to `VaListImpl`, similar to the previous [PR136969](rust-lang#136969).

This PR specifically adds requirements about argument availability for `VaListImpl::arg`, and also adds safety descriptions to the three associated intrinsic APIs.

Author: Zalathar

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.
+    /// - the next argument's type must be ABI-compatible with the type `T`.
+    /// - the next argument must have 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

@@ -3350,22 +3350,41 @@ 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.
+/// - the next argument's type must be ABI-compatible with the type `T`.
+/// - the next argument must have 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
+///
+/// `ap` must not be used to access variable arguments after this call.
+///
 #[rustc_intrinsic]
 #[rustc_nounwind]
 pub unsafe fn va_end(ap: &mut VaListImpl<'_>);