Docs

heim-common/src/errors.rs

@@ -8,10 +8,14 @@ use std::num;
 use std::path::PathBuf;
 use std::result;
 
-/// Result type used by `heim` API.
+/// A specialized Result type for data fetching functions.
+///
+/// This type is used almost for all `heim` routines
+/// for any operation which may produce an error.
 pub type Result<T> = result::Result<T, Error>;
 
 /// Error details.
+#[doc(hidden)]
 #[derive(Debug)]
 pub enum Context {
     /// Invalid data format, unable to parse file.
@@ -55,10 +59,14 @@ pub enum Context {
     __Nonexhaustive,
 }
 
-/// Error that might happen during the data fetch.
+/// Error type for data fetching operations.
+///
+/// Errors are originated from the underlying OS, data parsing
+/// or FFI call errors, and it should be assumed that this error
+/// is unrecoverable and data can't be fetched at all.
 ///
-/// In general it is assumed that any error is a some kind of IO error
-/// with an extra information about cause of a problem.
+/// Note: users **should not** rely on any internal API of this struct,
+/// as it is a subject of change in any moment.
 #[derive(Debug)]
 pub struct Error {
     source: io::Error,
@@ -110,6 +118,10 @@ impl Error {
     }
 
     /// Return error context if any.
+    ///
+    /// This method is considered to be an internal API
+    /// and should not be used by external parties.
+    #[doc(hidden)]
     pub fn context(&self) -> Option<&Context> {
         self.context.as_ref()
     }
@@ -118,6 +130,7 @@ impl Error {
     ///
     /// This method is considered to be an internal API
     /// and should not be used by external parties.
+    #[doc(hidden)]
     pub fn context_mut(&mut self) -> &mut Option<Context> {
         &mut self.context
     }
@@ -132,6 +145,10 @@ impl Error {
     }
 
     /// Returns reference to the inner `io::Error`.
+    ///
+    /// This method is considered to be an internal API
+    /// and should not be used by external parties.
+    #[doc(hidden)]
     pub fn as_inner(&self) -> &io::Error {
         &self.source
     }
@@ -222,8 +239,40 @@ impl Error {
 }
 
 impl fmt::Display for Error {
-    fn fmt(&self, _f: &mut fmt::Formatter) -> fmt::Result {
-        unimplemented!()
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        let _ = match &self.context {
+            Some(Context::SysCtl { ref name }) => {
+                f.write_fmt(format_args!("sysctl \"{:?}\" failed", name))
+            },
+            Some(Context::SysCtlByName { ref name }) => {
+                f.write_fmt(format_args!("sysctlbyname \"{:?}\" failed", name))
+            },
+            Some(Context::SysConf { name }) => {
+                f.write_fmt(format_args!("sysconf \"{}\" failed", name))
+            },
+            Some(Context::MissingKey { name, source }) => {
+                // TODO: That's ugly
+                if source.len() > 0 {
+                    f.write_fmt(format_args!("Unable to find required key \"{}\" in \"{}\"", name, source))
+                } else {
+                    f.write_fmt(format_args!("Unable to find required key \"{}\"", name))
+                }
+            },
+            Some(Context::File { path }) => {
+                f.write_fmt(format_args!("Unable to parse \"{}\", unsupported format", path.display()))
+            },
+            Some(Context::Message { text }) => {
+                f.write_str(text.as_ref())
+            },
+            Some(Context::Ffi { func }) => {
+                f.write_fmt(format_args!("FFI function \"{}\" call failed", func))
+            },
+            Some(other) => unreachable!("Nonexhaustive variant should be skipped for {:?}", other),
+            None => return fmt::Display::fmt(&self.source, f),
+        }?;
+
+        f.write_str(": ")?;
+        fmt::Display::fmt(&self.source, f)
     }
 }
 

heim/src/lib.rs

@@ -31,18 +31,20 @@
 //!
 //!  1. System components: each one of these enables functionality for fetching information
 //!     about some specific system part (ex. CPU or memory information).\
+//!     All these features are *disabled* by default.
 //!     See modules list below for available features.
 //!
 //!     Alternatively you can use `full` feature to enable all components at once.
 //!
-//!  2. Async runtimes support. Heim can be integrated with popular async runtimes
+//!  2. Async runtimes support. Heim can integrate with popular async runtimes
 //!     and also provides a fallback implementation for other use cases.
 //!
 //!     * `runtime-tokio`: Enables integration with [`tokio`](https://tokio.rs)
 //!     * `runtime-async-std`: Enables integration with [`async-std`](https://async.rs)
 //!     * `runtime-polyfill`: Enables bundled polyfill implementation for async routines.
 //!       Note that there are no guarantees provided about performance and properly asynchronous
-//!       execution for this implementation; other runtime integrations should be used preferably.
+//!       execution (*read: it might accidentally block*) for this implementation;
+//!       other runtime integrations should be used preferably.
 //!
 //!     None of these runtime features are enabled by default and you are required to
 //!     explicitly opt-in to use one of them.