API Docs: ptr #29371
Comments
…eklabnik Add examples for std::ptr module functions Part of rust-lang#29371. r? @steveklabnik
…klabnik add links to interesting items in `std::ptr` documentation Part of rust-lang#29371. r? @steveklabnik
…klabnik add links to interesting items in `std::ptr` documentation Part of rust-lang#29371. r? @steveklabnik
steveklabnik
added
the
E-mentor
|
I am happy to mentor anyone who wants to tackle this issue. |
steveklabnik
added
the
A-docs
steveklabnik
added
P-medium
|
@steveklabnik I'd like to help tackle this by taking on some of the items. Any general suggestions before I get started? I also have one question: any preference as to what website to use for linking to C standard library functions? How does this look for |
Wonderful! I left a bunch of related-ish comments on https://www.reddit.com/r/rust/comments/61avqf/want_to_join_the_rust_docs_team/?st=j0s6zfg8&sh=79419433. Of course, this whole exercise has brought up a meta issue, which is that our "how to contribute to docs" docs aren't as awesome as they could be. I'm gonna try to work on that 😄
This is a good question. I am not sure.
I haven't heard of this website before and I'm slightly skpetical of a wiki. I asked on Twitter, and got a number of responses:
I think I'm leaning towards MSDN here. |
|
Awesome. Thanks Steve. I'll get started on this in a few days (my semester's almost over). |
|
Hey @imiuka, sure! I was thinking of doing at least |
Mark-Simulacrum
added
the
C-tracking-issue
|
@lukaramu @hinaria: Want me to assign it to both of you "officially"? |
|
Hi all, sorry for my absence. I still like to do |
|
@GuillaumeGomez I'll tackle other modules first since there are people working on this one, thanks for asking though! |
|
I'm folding #36450 into this issue; basically, make sure that each function also mentions its requirements w.r.t. alignment. (Generally speaking, unless it says |
|
No worries! Glad you're feeling better! |
|
Newbie here, If no one's currently working on this, I'd like to pick it up. I've added the requisite information to A few questions:
Thanks! |
|
@ecstatic-morse that'd be great!
|
…bnik Rewrite docs for `std::ptr` This PR attempts to resolve rust-lang#29371. This is a fairly major rewrite of the `std::ptr` docs, and deserves a fair bit of scrutiny. It adds links to the GNU libc docs for various instrinsics, adds internal links to types and functions referenced in the docs, adds new, more complex examples for many functions, and introduces a common template for discussing unsafety of functions in `std::ptr`. All functions in `std::ptr` (with the exception of `ptr::eq`) are unsafe because they either read from or write to a raw pointer. The "Safety" section now informs that the function is unsafe because it dereferences a raw pointer and requires that any pointer to be read by the function points to "a valid vaue of type `T`". Additionally, each function imposes some subset of the following conditions on its arguments. * The pointer points to valid memory. * The pointer points to initialized memory. * The pointer is properly aligned. These requirements are discussed in the "Undefined Behavior" section along with the consequences of using functions that perform bitwise copies without requiring `T: Copy`. I don't love my new descriptions of the consequences of making such copies. Perhaps the old ones were good enough? Some issues which still need to be addressed before this is merged: - [ ] The new docs assert that `drop_in_place` is equivalent to calling `read` and discarding the value. Is this correct? - [ ] Do `write_bytes` and `swap_nonoverlapping` require properly aligned pointers? - [ ] The new example for `drop_in_place` is a lackluster. - [ ] Should these docs rigorously define what `valid` memory is? Or should is that the job of the reference? Should we link to the reference? - [ ] Is it correct to require that pointers that will be read from refer to "valid values of type `T`"? - [x] I can't imagine ever using `{read,write}_volatile` with non-`Copy` types. Should I just link to {read,write} and say that the same issues with non-`Copy` types apply? - [x] `write_volatile` doesn't link back to `read_volatile`. - [ ] Update docs for the unstable [`swap_nonoverlapping`](rust-lang#42818) - [ ] Update docs for the unstable [unsafe pointer methods RFC](rust-lang/rfcs#1966) Looking forward to your feedback. r? @steveklabnik
…bnik Rewrite docs for `std::ptr` This PR attempts to resolve rust-lang#29371. This is a fairly major rewrite of the `std::ptr` docs, and deserves a fair bit of scrutiny. It adds links to the GNU libc docs for various instrinsics, adds internal links to types and functions referenced in the docs, adds new, more complex examples for many functions, and introduces a common template for discussing unsafety of functions in `std::ptr`. All functions in `std::ptr` (with the exception of `ptr::eq`) are unsafe because they either read from or write to a raw pointer. The "Safety" section now informs that the function is unsafe because it dereferences a raw pointer and requires that any pointer to be read by the function points to "a valid vaue of type `T`". Additionally, each function imposes some subset of the following conditions on its arguments. * The pointer points to valid memory. * The pointer points to initialized memory. * The pointer is properly aligned. These requirements are discussed in the "Undefined Behavior" section along with the consequences of using functions that perform bitwise copies without requiring `T: Copy`. I don't love my new descriptions of the consequences of making such copies. Perhaps the old ones were good enough? Some issues which still need to be addressed before this is merged: - [ ] The new docs assert that `drop_in_place` is equivalent to calling `read` and discarding the value. Is this correct? - [ ] Do `write_bytes` and `swap_nonoverlapping` require properly aligned pointers? - [ ] The new example for `drop_in_place` is a lackluster. - [ ] Should these docs rigorously define what `valid` memory is? Or should is that the job of the reference? Should we link to the reference? - [ ] Is it correct to require that pointers that will be read from refer to "valid values of type `T`"? - [x] I can't imagine ever using `{read,write}_volatile` with non-`Copy` types. Should I just link to {read,write} and say that the same issues with non-`Copy` types apply? - [x] `write_volatile` doesn't link back to `read_volatile`. - [ ] Update docs for the unstable [`swap_nonoverlapping`](rust-lang#42818) - [ ] Update docs for the unstable [unsafe pointer methods RFC](rust-lang/rfcs#1966) Looking forward to your feedback. r? @steveklabnik
|
I'll reopen this issue because it doesn't feel like it's actually fixed. |
|
Triage: I have looked at all of the individual checkboxes, and 99% of the work here is done. I think these massive tracking issues have served their purpose; if you'd like to see more improvements to the |
Part of #29329
http://doc.rust-lang.org/std/ptr/
Here's what needs to be done to close out this issue:
*const T/*mut T, but it's really about common functions that work with them.copycould link tomemmovesomewhere.copy_nonoverlappingshould link tomemcpy. Both of these functions should talk more about what "overlapping" means here.drop_in_placeneeds links and examplesreadneeds to explain why and where you should use it, as well as linking some stuff.read_volitileneeds linksreplaceshould link tomem::replace, and justify its unsafety better.swapneeds to split out its summary from its description, link tomem::swap, and get an example.writeneeds to explain when and where to use it, and to link some typeswrite_bytesneeds to better justify itself, linkmemset, and move that out of its summary line.write_volatileneeds to linkread.The text was updated successfully, but these errors were encountered: