From 45d62f6f298a69bab6cd573c73eee2d13b7a37af Mon Sep 17 00:00:00 2001 From: Marcin Mielniczuk Date: Fri, 11 Oct 2019 20:12:07 +0200 Subject: [PATCH] Improve the doc --- Cargo.toml | 2 +- README.md | 10 ++++++++-- src/lib.rs | 10 ++++++++++ 3 files changed, 19 insertions(+), 3 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index 4bc0034..1d7444a 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "cvt" -version = "0.1.0" +version = "0.1.1" authors = ["Marcin Mielniczuk "] edition = "2018" license = "Apache-2.0" diff --git a/README.md b/README.md index 7faa4e6..1a3b2d1 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,12 @@ [crates-io]: https://crates.io/crates/cvt This package exposes the `cvt` function used extensively by `libstd` to -convert platform-specific syscall error codes. +convert platform-specific syscall error codes to `std::io::Result`. -The code was mostly copied over from Rust libstd. +Usually syscalls use return values for errors, the conventions differ. For instance, +on Unix `0` means success on Unix but failure on Windows. + +While those conventions are not always followed, they usually are and +`cvt` is there to reduce the mental bookkeeping and make it easier to handle syscall errors. + +The code was mostly copied over from Rust libstd, because the function is not public. diff --git a/src/lib.rs b/src/lib.rs index a07a527..3194bd6 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,3 +1,13 @@ +//! This package exposes the `cvt` function used extensively by `libstd` to +//! convert platform-specific syscall error codes to `std::io::Result`. +//! +//! Usually syscalls use return values for errors, the conventions differ. For instance, +//! on Unix `0` usually means success on Unix but failure on Windows. +//! While those conventions are not always followed, they usually are and +//! `cvt` is there to reduce the mental bookkeeping and make it easier to handle syscall errors. +//! +//! The code was mostly copied over from Rust libstd, because the function is not public. + cfg_if::cfg_if! { if #[cfg(target_os = "vxworks")] { mod vxworks;