BurntSushi/same-file

Do a pass over documentation

Closed this issue · 6 comments

KodrAus commented

Before the stable release, we should do a full pass over the crate documentation and make sure:

  • There aren't any grammatical errors in the prose
  • It all flows nicely
  • The examples are easy to follow and all make sense
  • The links to other items all work
gurgalex commented

broken trait links found under struct same_file::Handle
impl AsRawHandle for Handle
impl IntoRawHandle for Handle
All the links contain
/sys/imp/ext/

Valid links replace it with
/os/windows/
valid links are
AsRawHandle
IntoRawHandle

KodrAus commented

Thanks @gurgalex! Would you like to open a PR that fixes those up?

gurgalex commented

I'm not sure where or how the links are being generated sadly.
The src link points to here, but there are no links there. So I assume something is linking to the std library docs automatically.

gurgalex commented

How is cross platform defined?
Does that mean it supports all tier 1 platforms?

KodrAus commented

Oh I see, those are rustdoc links, not links we've added to the prose. It looks like the unix-specific links are all ok. Maybe there's just a mismatch between the nightly that generated the docs on docs.rs and where it ends up linking? I'm not really sure though, I'll do some digging but hopefully a new release will just magically fix that.

How is cross platform defined?

Excellent question! My reading is that it means all tier 1 platforms are fully supported with a consistent API.

BurntSushi commented

I did a brief pass over the docs and everything looks good to me. I don't think I checked every link, but we can clean those up whenever.