quinn
quinn copied to clipboard
docs(quinn): Revise SendStream::write docs
Aligns with 100 columns, attempts to improve clarity, takes inspiration from tokio::io::AsyncWriteExt docs.
Initial bikeshedding:
- Why introduce "resolves to" in addition to "yields"?
- Why replace "cancel-safe" with "cancellation safe"?
* Why replace "cancel-safe" with "cancellation safe"?
This mirrors how tokio talks about it. They use a section header named Cancel safety and in prose use "This method is cancellation safe".
@gretchenfrage want to polish this up so we can merge it?
@djc Yeah, I'd like to prioritize #2168 personally because I don't like how long I've been blocking it. I haven't lost track of anything, I just haven't had capacity for a while.
@djc Yeah, I'd like to prioritize #2168 personally because I don't like how long I've been blocking it. I haven't lost track of anything, I just haven't had capacity for a while.
Would be nice to get this over the finish line.
My revision of this PR is in-progress, I'm hoping I can put it back into review tomorrow. I appreciate your patience with me as my capacity has been reduced a lot recently.
- Rebased over main
- Changed the first lines of comments to be imperative, for stylistic consistency with rest of project
- No longer starting first line of docs with "Attempt to" (Tokio sometimes does that but sometimes not. My
reasoning for removing it is that we don't need to explicitly say that a method which returns a
Resultmight fail any more than we need to explicitly say that a method which isasyncreturns a future, at least within the first line of the doc comment.) - Take flub's suggestion to use Tokio-inspired
# Cancel safetyheaders - Slight tweaks / corrections to my own grammar
- Take Ralith's suggestion to replace phrase "resolves to" with "yields"
- No longer rearranging order of methods