List of functions with missing safety docs

[RealKC]

During the discussion on the matrix channel which prompted me to open #629, I mentioned I'd take a look for more functions that were unsafe yet lacked a safety section in their documentation, and open an issue. I was told this would be welcome, so here's that issue.

Methodology: I used VSCode's Search panel to search for pub unsafe fn and manually inspected each function.

Cairo

The following do not include safety docs:

• Context::from_raw_none
• Context::from_raw_borrow
• Context::from_raw_full
• Device::from_raw_none
• Device::from_raw_borrow
• Device::from_raw_full
• Path::from_raw_full
• Pattern::from_raw_none
• Pattern::from_raw_full
• Region::from_raw_none
• Region::from_raw_borrow
• Region::from_raw_full
• Generated surface from_raw_full and from_raw_none through the declare_surface! macro
• Surface::from_raw_none
• Surface::from_raw_borrow
• Surface::from_raw_full
• Surface::mime_data_raw
• ~~utils::debug_reset_static_data~~
• XCBConnection::from_raw_none
• XCBConnection::from_raw_borrow
• XCBConnection::from_raw_full
• XCBRenderPictFormInfo::from_raw_none
• XCBRenderPictFormInfo::from_raw_borrow
• XCBRenderPictFormInfo::from_raw_full
• XCBScreen::from_raw_full
• XCBScreen::from_raw_none
• XCBScreen::from_raw_borrow
• XCBVisualType::from_raw_full
• XCBVisualType::from_raw_none
• XCBVisualType::from_raw_borrow
• FontFace::from_raw_full
• FontFace::from_raw_none
• FontOptions::from_raw_full
• FontOptions::from_raw_none
• ScaledFont::from_raw_full
• ScaledFont::from_raw_none

The following have safety comments where the function is defined, but as it's written like a normal comment, it won't be shown on the generated docs (or on hover by IDEs):

• ~~FontFace::create_from_ft~~
• ~~FontFace::create_from_ft_with_flags~~

Gio

The following do not include safety docs:

• CancelledHandlerId::as_raw - this is unsafe despite just casting an integer to another integer, but it also assumes that c_ulong can fit all NonZeroU64 values which I believe to not be true on Windows
• Socket::from_fd
• Socket::from_socket
• Generated new with task_impl!, but also return_error_if_cancelled, return_result, propagate though only if the macro is explicitly passed unsafe to its @safety param
• ~~UnixInputStream::take_fd~~
• ~~UnixInputStream::with_fd~~
• ~~UnixOutputStream::take_fd~~
• ~~UnixOutputStream::with_fd~~
• ~~Win32InputStream::take_handle~~
• ~~Win32OutputStream::with_handle~~
• ~~Win32OutputStream::with_handle~~

Glib

The following do not include safety docs:

• PtrSlice::from_glib_borrow_num
• PtrSlice::from_glib_container_num
• Ptrslice::from_glib_full_num
• PtrSlice::from_glib_container
• PtrSlice::from_glib_full
• Slice::from_glib_borrow_num
• Slice::from_glib_container_num_copy
• Slice::from_glib_container_num
• Slice::from_glib_full_num_copy
• Slice::from_glib_full_num
• List::from_glib_container
• List::from_glib_full
• SList::from_glib_container
• SList::from_glib_full
• ~~log::log_writer_default_set_use_stderr~~
• TypedObjectRef::new
• ~~WatchedObject::borrow~~
• SignalHandlerId - just like CancelledHandlerId::as_raw it's unsafe despite just casting one integer type to another, and assumes that c_ulong can fit all NonZeroU64 values which I believe to not be true on Windows
• signal::connect_raw
• SourceId - unsafe despite just returning an integer
• translate::unitialized and the Unitialized trait
• translate::from_glib
• translate::try_from_glib
• translate::from_glib_none
• translate::from_glib_full
• translate::from_glib_borrow
• translate::c_ptr_array_len
• types::instance_of
• VariantTy::from_ptr

The following detail their safety preconditions, but not explicitly under a safety section, I don't know if anything should be done about them, but I decided to list them anyway:

• PtrSlice::from_glib_none_num_static
• PtrSlice::from_glib_container_num_static
• PtrSlice::from_glib_none_static
• PtrSlice::fromg_glib_container_static
• Slice::from_glib_none_num_static
• Slice::from_glib_container_num_static
• List::from_glib_none_static
• List::from_glib_container_static
• SList::from_glib_none_static
• SList::from_glib_container_static
• GStr::from_ptr

---

Notes:

• a number of these can panic, and documentation for why they could panic would be nice
• I didn't check whether these functions actually get exported outside the crate they're defined in, but I don't think that matters too much?

[jf2048]

• TypedObjectRef::new

• WatchedObject::borrow

These are only used internally by macros, it seems like they should be #[doc(hidden)]?

[RealKC]

These are only used internally by macros, it seems like they should be #[doc(hidden)]?

WatchedObject is fully #[doc(hidden)] so its borrow method won't show in docs anyway I believe. I included it in the list because I believe there'd be value in its safety preconditions being documented though for the developers working on these crates

[sdroege]

CancelledHandlerId::as_raw - this is unsafe despite just casting an integer to another integer, but it also assumes that c_ulong can fit all NonZeroU64 values which I believe to not be true on Windows

That's actually OK. CancelledHandlerId is created from a c_ulong only, which always fits into an u64 on all the platforms we support. There's no conditional compilation to switch to a NonZeroU32 because that would just complicate the code for not much improvement. (long is 32 bit on 64 bit Windows and 64 bit on almost any other 64 bit architecture).

• a number of these can panic, and documentation for why they could panic would be nice

• I didn't check whether these functions actually get exported outside the crate they're defined in, but I don't think that matters too much?

I agree