quinn icon indicating copy to clipboard operation
quinn copied to clipboard

docs(quinn): Revise SendStream::write docs

Open gretchenfrage opened this issue 6 months ago • 2 comments

Aligns with 100 columns, attempts to improve clarity, takes inspiration from tokio::io::AsyncWriteExt docs.

gretchenfrage avatar May 10 '25 18:05 gretchenfrage

Initial bikeshedding:

  • Why introduce "resolves to" in addition to "yields"?
  • Why replace "cancel-safe" with "cancellation safe"?

Ralith avatar May 10 '25 23:05 Ralith

* 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".

flub avatar May 14 '25 10:05 flub

@gretchenfrage want to polish this up so we can merge it?

djc avatar Jul 07 '25 08:07 djc

@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.

gretchenfrage avatar Jul 07 '25 22:07 gretchenfrage

@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.

djc avatar Aug 12 '25 10:08 djc

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.

gretchenfrage avatar Aug 13 '25 04:08 gretchenfrage

  • 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 Result might fail any more than we need to explicitly say that a method which is async returns a future, at least within the first line of the doc comment.)
  • Take flub's suggestion to use Tokio-inspired # Cancel safety headers
  • Slight tweaks / corrections to my own grammar
  • Take Ralith's suggestion to replace phrase "resolves to" with "yields"
  • No longer rearranging order of methods

gretchenfrage avatar Aug 14 '25 04:08 gretchenfrage