WIP: Update core::io and alloc::io Documentation - #160413
Conversation
rustbot
added
S-waiting-on-author
f5002df to
d5b15db
Compare
| /// | ||
| /// # Example | ||
| /// | ||
| /// ``` | ||
| /// # // This test requires unwinding to work. | ||
| /// # // Disable it when unwinding isn't available. | ||
| /// # #[cfg(panic = "unwind")] | ||
| /// # fn main() { | ||
| /// use std::io::{self, BufWriter, Write}; | ||
| /// use std::panic::{catch_unwind, AssertUnwindSafe}; | ||
| /// | ||
| /// struct PanickingWriter; | ||
| /// impl Write for PanickingWriter { | ||
| /// fn write(&mut self, buf: &[u8]) -> io::Result<usize> { panic!() } | ||
| /// fn flush(&mut self) -> io::Result<()> { panic!() } | ||
| /// } | ||
| /// | ||
| /// let mut stream = BufWriter::new(PanickingWriter); | ||
| /// write!(stream, "some data").unwrap(); | ||
| /// let result = catch_unwind(AssertUnwindSafe(|| { | ||
| /// stream.flush().unwrap() | ||
| /// })); | ||
| /// assert!(result.is_err()); | ||
| /// let (recovered_writer, buffered_data) = stream.into_parts(); | ||
| /// assert!(matches!(recovered_writer, PanickingWriter)); | ||
| /// assert_eq!(buffered_data.unwrap_err().into_inner(), b"some data"); | ||
| /// # } | ||
| /// # #[cfg(not(panic = "unwind"))] | ||
| /// # fn main() {} | ||
| /// ``` |
There was a problem hiding this comment.
Since this example relies on catch_unwind, it requires std. I've removed it temporarily, but maybe this needs to be added back to WriterPanicked (maybe on the use alloc_crate::io::WriterPanicked re-export in std?)
| /// # Examples | ||
| /// | ||
| /// ```no_run | ||
| /// # use std::io; | ||
| /// fn main() -> io::Result<()> { | ||
| /// let stdin = io::read_to_string(io::stdin())?; | ||
| /// println!("Stdin was:"); | ||
| /// println!("{stdin}"); | ||
| /// Ok(()) | ||
| /// } | ||
| /// ``` | ||
| /// |
There was a problem hiding this comment.
Not sure what to do about this example; I think without stdin this example would be too small to really be worth writing?
This comment has been minimized.
This comment has been minimized.
d7f6431 to
d6f3477
Compare
This comment has been minimized.
This comment has been minimized.
| /// | ||
| /// fn main() -> std::io::Result<()> { | ||
| /// let f1 = File::open("log.txt")?; | ||
| /// let f1 = b"Hello\nWorld!" as &[u8]; |
There was a problem hiding this comment.
I think it is reasonable to keep the old code. It better explains what kind of use cases BufReader is meant for (reads involving actual IO that is cheaper when batched).
There was a problem hiding this comment.
I do think the old examples are generally better, but I'm not sure if there's any issues with having examples in alloc which require std? If it's acceptable to have example code in alloc and core which requires std I'm happy to revert those changes.
There was a problem hiding this comment.
Actually yeah, based on the existing documentation for something like core::borrow, it looks like it's expected that std be available for example snippets. Tomorrow morning I'll close this PR in favor of just the prelude and a handful of other minor changes. Thanks for your help!
|
Closing in favour of #160472. I chose to open a fresh PR and leave this closed so that if someone did want to make the snippets |
rustbot
removed
the
S-waiting-on-author
4 participants
ACP: rust-lang/libs-team#755
Tracking issue: #154046
Description
Now that
core::ioandalloc::iocontain a significant proportion of formerlystd-only code, there's a lot of documentation that requires updating to ensureno_stdusers are provided relevant information. For example, a lot of demonstration code relies onFile, which is not available inallocorcore. Further, this comment on #156527, and #160151 have both identified similar issues.Solution
BufWriter'sTcpStreamexample code to theTcpStreamtype. The example is useful and worth preserving, but would need to be completely replaced if left inalloc.core::ioandalloc::ioto usecoreandalloccompatible types where they previously relied onstdin,File,TcpStream, etc.use core as std;(and similar) statements to ensure the live documentation on docs.rs shows stable paths, since these types are re-exported fromstd.Notes