Add TcpStream type to TcpListener::incoming docs#87874
Merged
bors merged 1 commit intorust-lang:masterfrom Aug 19, 2021
schneems:schneems/tcpstream-iterator-type
Merged
Add TcpStream type to TcpListener::incoming docs#87874bors merged 1 commit intorust-lang:masterfrom schneems:schneems/tcpstream-iterator-type
bors merged 1 commit intorust-lang:masterfrom
schneems:schneems/tcpstream-iterator-type
Conversation
Contributor
|
Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @Mark-Simulacrum (or someone else) soon. Please see the contribution instructions for more information. |
While going through the "The Rust Programming Language" book (Klabnik & Nichols), the TCP server example directs us to use TcpListener::incoming. I was curious how I could pass this value to a function (before reading ahead in the book), so I looked up the docs to determine the signature. When I opened the docs, I found https://doc.rust-lang.org/std/net/struct.TcpListener.html#method.incoming, which didn't mention TcpStream anywhere in the example. Eventually, I clicked on https://doc.rust-lang.org/std/net/struct.TcpListener.html#method.accept in the docs (after clicking a few other locations first), and was able to surmise that the value contained TcpStream. ## Opportunity While this type is mentioned several times in this doc, I feel that someone should be able to fully use the results of the TcpListner::incoming iterator based solely on the docs of just this method. ## Implementation I took the code from the top-level TcpListener https://doc.rust-lang.org/std/net/struct.TcpListener.html#method.incoming and blended it with the existing docs for TcpListener::incoming https://doc.rust-lang.org/std/net/struct.TcpListener.html#method.incoming. It does make the example a little longer, and it also introduces a little duplication. It also gives the reader the type signatures they need to move on to the next step. ## Additional considerations I noticed that in this doc, `handle_connection` and `handle_client` are both used to accept a TcpStream in the docs on this page. I want to standardize on one function name convention, so readers don't accidentally think two different concepts are being referenced. I didn't want to cram do too much in one PR, I can update this PR to make that change, or I could send another PR (if you would like). First attempted contribution to Rust (and I'm also still very new, hence reading through the rust book for the first time)! Would you please let me know what you think?
|
@matthew-piziak Hi friend! I thought of you as our team was learning rust and going through the Rust book. |
Contributor
Member
|
@bors r+ rollup Thank you! I agree that explicitly indicating the iterator type like this seems beneficial in this case, and helps be uniform with the top-level example too. Updating handle_connection or handle_client names to standardize on one name seems reasonable, please feel free to file a new PR with that. |
Collaborator
|
📌 Commit 2d639ce has been approved by |
bors
added a commit
to rust-lang-ci/rust
that referenced
this pull request
Aug 19, 2021
…laumeGomez Rollup of 8 pull requests Successful merges: - rust-lang#86123 (Preserve more spans in internal `rustc_queries!` macro) - rust-lang#87874 (Add TcpStream type to TcpListener::incoming docs) - rust-lang#88034 (rustc_privacy: Replace `HirId`s and `DefId`s with `LocalDefId`s where possible) - rust-lang#88050 (Remove `HashStable` impls for `FileName` and `RealFileName`) - rust-lang#88093 ([rustdoc] Wrap code blocks in `<code>` tag) - rust-lang#88146 (Add tests for some `feature(const_evaluatable_checked)` incr comp issues) - rust-lang#88153 (Update .mailmap) - rust-lang#88159 (Use a trait instead of the now disallowed missing trait there) Failed merges: r? `@ghost` `@rustbot` modify labels: rollup
Contributor
Author
|
Thank you! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Context
While going through the "The Rust Programming Language" book (Klabnik & Nichols), the TCP server example directs us to use TcpListener::incoming. I was curious how I could pass this value to a function (before reading ahead in the book), so I looked up the docs to determine the signature.
When I opened the docs, I found https://doc.rust-lang.org/std/net/struct.TcpListener.html#method.incoming, which didn't mention TcpStream anywhere in the example.
Eventually, I clicked on https://doc.rust-lang.org/std/net/struct.TcpListener.html#method.accept in the docs (after clicking a few other locations first), and was able to surmise that the value contained TcpStream.
Opportunity
While this type is mentioned several times in this doc, I feel that someone should be able to fully use the results of the TcpListner::incoming iterator based solely on the docs of just this method.
Implementation
I took the code from the top-level TcpListener https://doc.rust-lang.org/std/net/struct.TcpListener.html#method.incoming and blended it with the existing docs for TcpListener::incoming https://doc.rust-lang.org/std/net/struct.TcpListener.html#method.incoming.
It does make the example a little longer, and it also introduces a little duplication. It also gives the reader the type signatures they need to move on to the next step.
Additional considerations
I noticed that in this doc,
handle_connectionandhandle_clientare both used to accept a TcpStream in the docs on this page. I want to standardize on one function name convention, so readers don't accidentally think two different concepts are being referenced. I didn't want to cram do too much in one PR, I can update this PR to make that change, or I could send another PR (if you would like).First attempted contribution to Rust (and I'm also still very new, hence reading through the rust book for the first time)! Would you please let me know what you think?