Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve documentation of std::ptr::NonNull #48929

Open
crlf0710 opened this issue Mar 11, 2018 · 3 comments

Comments

@crlf0710
Copy link
Contributor

commented Mar 11, 2018

This type used to be experimental and internal (when it was called Shared), now that it is finally being stablized (see #27730, #47631), people are complaining that the current document texts are not easy to understand.

Current text *mut T but non-zero and covariant. talks about the covariance, which is not mentioned elsewhere in the libstd docs and the Rust books. (I know it's mentioned in Nomicon but beginners seldom have read it.)

I suggest the docs be either supplemented with concrete explanations or reworked upon.

@crlf0710 crlf0710 changed the title Documentation of std::ptr::NonNull Improve documentation of std::ptr::NonNull Mar 11, 2018

@frewsxcv frewsxcv added the T-doc label Mar 11, 2018

@frewsxcv

This comment has been minimized.

Copy link
Member

commented Mar 26, 2018

worth mentioning that the nomicon has a section on covriance: https://doc.rust-lang.org/beta/nomicon/subtyping.html

@mjbshaw

This comment has been minimized.

Copy link
Contributor

commented Apr 20, 2018

One question I have that I'd love to be explicitly answered:

Does NonNull<T> have the same ABI as *mut T?

The Nomicon says "If T is an FFI-safe non-nullable pointer type, Option<T> is guaranteed to have the same layout and ABI as T and is therefore also FFI-safe." This documentation and explicit statement gives some guarantees regarding Option, and it's really nice to be able to use Option in FFI code. I would love to have similar guarantees and documentation for NonNull so I could use it in some FFI-related code. But before I can use NonNull I need to make sure that I won't accidentally change my code's ABI.

@steveklabnik

This comment has been minimized.

Copy link
Member

commented Dec 27, 2018

Other issues: #52978

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
5 participants
You can’t perform that action at this time.