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

API Docs: net #29363

Closed
steveklabnik opened this Issue Oct 26, 2015 · 3 comments

Comments

Projects
None yet
3 participants
@steveklabnik
Member

steveklabnik commented Oct 26, 2015

Part of #29329

http://doc.rust-lang.org/std/net/

Here's what needs to be done to close out this issue:

  • the module documentation is very tiny and needs expanded.
  • ParseError needs to link to where it comes from and have examples.
  • Incoming should use the standard iterator boilerplate and move its semantics into the method docs.
  • Ipv4Addr needs better top-level docs and should link to IpAddr
  • many places in these docs should say "IETF RFC" rather than "RFC", as we have Rust RFCs as well.
  • Ipv6Addr same as Ipv4Addr.
  • SocketAddrV4 has poor top-level docs and needs to have a defined summary/explanation split. Its methods are okay, but very short. It needs to link to SocketAddr.
  • SocketAddrV6 same
  • TcpListener's docs don't really say what it is.
  • TcpStream's the same.
  • UpdSocket is the same.
  • IpAddr should link to an IETF RFC
  • Shutdown should use the standard boilerplate
  • SocketAddr has very short docs.
  • ToSocketAddrs needs a lot of links.
@apoelstra

This comment has been minimized.

Contributor

apoelstra commented Feb 17, 2016

Hi,

https://doc.rust-lang.org/std/net/struct.Incoming.html

Says that the Incoming iterator will return an infinite list of incoming connections. In fact, it may error out (for example if the system runs out of file descriptors) and return an infinite list of errors, with no delays in between. A naive "log and retry" loop may become a spinloop in this case, pegging the CPU and/or filling log space.

@steveklabnik

This comment has been minimized.

Member

steveklabnik commented Mar 8, 2017

I am happy to mentor anyone who wants to tackle this issue.

@lukaramu

This comment has been minimized.

Contributor

lukaramu commented Mar 24, 2017

I'm gonna try to tackle (parts of?) the docs for TcpListener & TcpStream, especially with regard to #40322 since I've been digging information for that up anyway; I'll probably grab some low-hanging fruit beforehand though.

lukaramu added a commit to lukaramu/rust that referenced this issue Mar 26, 2017

lukaramu added a commit to lukaramu/rust that referenced this issue Mar 26, 2017

lukaramu added a commit to lukaramu/rust that referenced this issue Mar 26, 2017

Added links throughout std::net::ToSocketAddrs' documentation
Part of rust-lang#29363

In the section about the default implementations of ToSocketAddrs,
I moved the bulletpoint of SocketAddrV4 & SocketAddrV6 to the one
stating that SocketAddr is constructed trivially, as this is what's
actually the case

lukaramu added a commit to lukaramu/rust that referenced this issue Mar 26, 2017

Expanded and added links to std::net::{IpAddr,Ipv4Addr,Ipv6Addr} docs
Part of rust-lang#29363
Expanded top-level documentation & linked to relevant IETF RFCs.
Added a bunch of links (to true/false/Ipv4Addr/etc.) throughout the docs.

lukaramu added a commit to lukaramu/rust that referenced this issue Mar 26, 2017

lukaramu added a commit to lukaramu/rust that referenced this issue Mar 26, 2017

Added links throughout std::net::ToSocketAddrs' documentation
Part of rust-lang#29363

In the section about the default implementations of ToSocketAddrs,
I moved the bulletpoint of SocketAddrV4 & SocketAddrV6 to the one
stating that SocketAddr is constructed trivially, as this is what's
actually the case

lukaramu added a commit to lukaramu/rust that referenced this issue Mar 26, 2017

Expanded and added links to std::net::{IpAddr,Ipv4Addr,Ipv6Addr} docs
Part of rust-lang#29363
Expanded top-level documentation & linked to relevant IETF RFCs.
Added a bunch of links (to true/false/Ipv4Addr/etc.) throughout the docs.

lukaramu added a commit to lukaramu/rust that referenced this issue Mar 26, 2017

Expanded and added links to std::net::{SocketAddr,SocketAddrV4,Socket…
…AddrV6} docs

Part of rust-lang#29363
Changed summary sentences of SocketAddr and IpAddr for consistency
Linked to SocketAddrV4 and SocketAddrV6 from SocketAddr, moving explaination
there
Expanded top-level docs for SocketAddrV4 and SocketAddrV6, linking to some
relevant IETF RFCs, and linking back to SocketAddr
Changed some of the method summaries to third person as per RFC 1574; added
links to IETF RFCs where appropriate

lukaramu added a commit to lukaramu/rust that referenced this issue Mar 26, 2017

lukaramu added a commit to lukaramu/rust that referenced this issue Mar 26, 2017

Added links throughout std::net::ToSocketAddrs' documentation
Part of rust-lang#29363

In the section about the default implementations of ToSocketAddrs,
I moved the bulletpoint of SocketAddrV4 & SocketAddrV6 to the one
stating that SocketAddr is constructed trivially, as this is what's
actually the case

lukaramu added a commit to lukaramu/rust that referenced this issue Mar 26, 2017

Expanded and added links to std::net::{IpAddr,Ipv4Addr,Ipv6Addr} docs
Part of rust-lang#29363
Expanded top-level documentation & linked to relevant IETF RFCs.
Added a bunch of links (to true/false/Ipv4Addr/etc.) throughout the docs.

lukaramu added a commit to lukaramu/rust that referenced this issue Mar 26, 2017

Expanded and added links to std::net::{SocketAddr,SocketAddrV4,Socket…
…AddrV6} docs

Part of rust-lang#29363
Changed summary sentences of SocketAddr and IpAddr for consistency
Linked to SocketAddrV4 and SocketAddrV6 from SocketAddr, moving explaination
there
Expanded top-level docs for SocketAddrV4 and SocketAddrV6, linking to some
relevant IETF RFCs, and linking back to SocketAddr
Changed some of the method summaries to third person as per RFC 1574; added
links to IETF RFCs where appropriate

lukaramu added a commit to lukaramu/rust that referenced this issue Mar 26, 2017

lukaramu added a commit to lukaramu/rust that referenced this issue Mar 26, 2017

lukaramu added a commit to lukaramu/rust that referenced this issue Mar 26, 2017

Added links throughout std::net::ToSocketAddrs' documentation
Part of rust-lang#29363

In the section about the default implementations of ToSocketAddrs,
I moved the bulletpoint of SocketAddrV4 & SocketAddrV6 to the one
stating that SocketAddr is constructed trivially, as this is what's
actually the case

lukaramu added a commit to lukaramu/rust that referenced this issue Mar 26, 2017

Expanded and added links to std::net::{IpAddr,Ipv4Addr,Ipv6Addr} docs
Part of rust-lang#29363
Expanded top-level documentation & linked to relevant IETF RFCs.
Added a bunch of links (to true/false/Ipv4Addr/etc.) throughout the docs.

lukaramu added a commit to lukaramu/rust that referenced this issue Mar 26, 2017

Expanded and added links to std::net::{SocketAddr,SocketAddrV4,Socket…
…AddrV6} docs

Part of rust-lang#29363
Changed summary sentences of SocketAddr and IpAddr for consistency
Linked to SocketAddrV4 and SocketAddrV6 from SocketAddr, moving explaination
there
Expanded top-level docs for SocketAddrV4 and SocketAddrV6, linking to some
relevant IETF RFCs, and linking back to SocketAddr
Changed some of the method summaries to third person as per RFC 1574; added
links to IETF RFCs where appropriate

lukaramu added a commit to lukaramu/rust that referenced this issue Mar 26, 2017

frewsxcv added a commit to frewsxcv/rust that referenced this issue Mar 29, 2017

Rollup merge of rust-lang#40838 - lukaramu:std-net-docs, r=GuillaumeG…
…omez

Improve std::net docs

Fixes rust-lang#29363

Summary:
* Added a _lot_ of missing links, both to other types/methods and to IETF RFCs, and changed occurences of just "RFC" to "IETF RFC"
* Expanded a bunch of top-level docs, specifically the module docs & the docs for `TcpListener`, `TcpStream`, `UdpSocket`, `IpAddr`, `Ipv4Addr`, `Ipv6Addr`, `SocketAddr`, `SocketAddrV4`, `SocketAddrV6`,
* Expanded method docs for `SocketAddrV6`, `AddrParseError`,
* Various edits for clarity, consistency, and accuracy

See the commit descriptions for more detail.

Things not done quite as laid out in the task list in rust-lang#29363:
* `AddrParseError` still doesn't have examples, but I wasn't quite sure how to do them; other `FromStr` error types don't have any, either
* I didn't link to an IETF RFC in `IpAddr`, but in `Ipv4Addr` and `Ipv6Addr` and linked tho those from `IpAddr`; this seems more appropriate to me
* Similarly, I didn't really exand `SocketAddr`'s docs, but elaborated on `SocketAddrV4` and `SocketAddrV6`'s and linked to them from `SocketAddr`

Theres definitely still room for improvement, but this should be a good first effort 😄

frewsxcv added a commit to frewsxcv/rust that referenced this issue Mar 29, 2017

Rollup merge of rust-lang#40838 - lukaramu:std-net-docs, r=GuillaumeG…
…omez

Improve std::net docs

Fixes rust-lang#29363

Summary:
* Added a _lot_ of missing links, both to other types/methods and to IETF RFCs, and changed occurences of just "RFC" to "IETF RFC"
* Expanded a bunch of top-level docs, specifically the module docs & the docs for `TcpListener`, `TcpStream`, `UdpSocket`, `IpAddr`, `Ipv4Addr`, `Ipv6Addr`, `SocketAddr`, `SocketAddrV4`, `SocketAddrV6`,
* Expanded method docs for `SocketAddrV6`, `AddrParseError`,
* Various edits for clarity, consistency, and accuracy

See the commit descriptions for more detail.

Things not done quite as laid out in the task list in rust-lang#29363:
* `AddrParseError` still doesn't have examples, but I wasn't quite sure how to do them; other `FromStr` error types don't have any, either
* I didn't link to an IETF RFC in `IpAddr`, but in `Ipv4Addr` and `Ipv6Addr` and linked tho those from `IpAddr`; this seems more appropriate to me
* Similarly, I didn't really exand `SocketAddr`'s docs, but elaborated on `SocketAddrV4` and `SocketAddrV6`'s and linked to them from `SocketAddr`

Theres definitely still room for improvement, but this should be a good first effort 😄

frewsxcv added a commit to frewsxcv/rust that referenced this issue Mar 29, 2017

Rollup merge of rust-lang#40838 - lukaramu:std-net-docs, r=GuillaumeG…
…omez

Improve std::net docs

Fixes rust-lang#29363

Summary:
* Added a _lot_ of missing links, both to other types/methods and to IETF RFCs, and changed occurences of just "RFC" to "IETF RFC"
* Expanded a bunch of top-level docs, specifically the module docs & the docs for `TcpListener`, `TcpStream`, `UdpSocket`, `IpAddr`, `Ipv4Addr`, `Ipv6Addr`, `SocketAddr`, `SocketAddrV4`, `SocketAddrV6`,
* Expanded method docs for `SocketAddrV6`, `AddrParseError`,
* Various edits for clarity, consistency, and accuracy

See the commit descriptions for more detail.

Things not done quite as laid out in the task list in rust-lang#29363:
* `AddrParseError` still doesn't have examples, but I wasn't quite sure how to do them; other `FromStr` error types don't have any, either
* I didn't link to an IETF RFC in `IpAddr`, but in `Ipv4Addr` and `Ipv6Addr` and linked tho those from `IpAddr`; this seems more appropriate to me
* Similarly, I didn't really exand `SocketAddr`'s docs, but elaborated on `SocketAddrV4` and `SocketAddrV6`'s and linked to them from `SocketAddr`

Theres definitely still room for improvement, but this should be a good first effort 😄

@bors bors closed this in #40838 Mar 29, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment