Improve documentation

[kupiakos]

• [ ] Top-level usage examples of write-only/out references
• [ ] Make safety documentation and language consistent (and more consistent with upstream terminology)
• [ ] Usage examples for every single method
• [ ] Give top-level usage examples in the README as well

[kupiakos]

Some requested top-level usage examples for Out (this list will be edited as further examples are requested):

• Initializing a slice with another slice
• Initializing a slice with random data
• Initializing a FromBytes type with a non-zero byte value
• Converting from raw pointers to Out, slice and Sized
• Constructing Out from initialized data, slice and Sized
• Constructing Out from uninit data, slice and Sized

[vsukhoml]

I'd also add construction of empty output slice like Out::from(&mut []) which doesn't work out of the box.

Another suggestion - more From patterns like From<MaybeUninit<[T; N]>> and From<[MaybeUninit<T>; N]>.

When dealing with C FFI code I found that from_raw_parts_mut would be a nice feature of Out

[kupiakos]

@vsukhoml

Adding these features already have tracking issues from our conversations - though feel free to post additional examples or doc improvements you'd like to see. 😄

I'd also add construction of empty output slice like Out::from(&mut []) which doesn't work out of the box.

22

Another suggestion - more From patterns like From<MaybeUninit<[T; N]>> and From<[MaybeUninit<T>; N]>.

23

When dealing with C FFI code I found that from_raw_parts_mut would be a nice feature of Out

11