Merge pull request #36 from apogeeoak/documentation

Update documentation.

changelog.md

@@ -1,3 +1,9 @@
+# Changelog
+
+## v2.0.1 (2021-08-15)
+
+Update documentation. No functionality changes.
+
 ## v2.0.0 (2021-07-25)
 
 **Breaking**: Change result from `io::Result<ExitStatus>` to `io::Result<()>`.
@@ -7,22 +13,13 @@ issues with particular programs reporting success even on error, doing error han
 close to impossible.
 This releases alleviates most of the issues.
 
-Error information is gathered from the stderr channel of the process using a single read operation.
-This prevents the child process from keeping the main process alive if stderr is kept open.
-
 ## Notes
 
 `wslview` always reports a 0 exit status, even if the path does not exist, which results in false positives.
-The stderr channel is written to but ignored in this implementation because of the successful exit status.
-Other programs write to stderr as part of normal operation. Firefox on Linux never seems to be able to load all 
-the modules it wants to, so it writes to stderr but successfully opens. The only way to avoid these false positives
-is to special case wsl or for `wslview` to fix the unsuccessful exit status bug.
-This is only a minor problem and can mostly be ignored.
 
-## v1.7.0 (2021-07-17)
+## v1.7.1 (2021-07-17)
 
-* improved support [for
-  windows-subsystem-for-linux](https://github.com/Byron/open-rs/pull/33#issue-691044025)
+* Improved support for [Windows Subsystem for Linux](https://github.com/Byron/open-rs/pull/33#issue-691044025)
 
 ## v1.7.0 (2021-04-18)
 
@@ -63,37 +60,27 @@ YANKED to avoid potential for breakage by using 'explorer.exe' to open URLs.
 * **windows**: escape '&' in URLs. On windows, a shell is used to execute the command, which
   requires certain precautions for the URL to open to get through the interpreter.
 
+## v1.1.1 (2016-04-10)
 
-<a name="v1.1.1"></a>
-### v1.1.1 (2016-04-10)
-
-
-#### Bug Fixes
+### Bug Fixes
 
 * **cargo:**  no docs for open ([31605e0e](https://github.com/Byron/open-rs/commit/31605e0eddfb0cf8db635dd4d86131bc46beae78))
 
-#### Improvements
+### Improvements
 
 * **api:**  allow OSStrings instead of &str ([1d13a671](https://github.com/Byron/open-rs/commit/1d13a671f2c9bd9616bf185fac77b32da1dcf8ee))
 
-
-
-<a name="25c0e398"></a>
 ## 25c0e398 (2015-07-08)
 
-
-#### Features
+### Features
 
 * **open**  added 'open' program ([a4c3a352](https://github.com/Byron/open-rs/commit/a4c3a352c8f912211d5ab48daaf41cb847ebcc0c))
 
-#### Bug Fixes
+### Bug Fixes
 
 * **cargo**  description added ([0fcafb56](https://github.com/Byron/open-rs/commit/0fcafb56cdb5d154b3e983d17c93a1dd7c665426))
 * **open**
-  *  use result ([25c0e398](https://github.com/Byron/open-rs/commit/25c0e398856c24a2daf0444640567ed3fd2f4307))
-  *  don't use 'open' on linux ([30c96b1c](https://github.com/Byron/open-rs/commit/30c96b1cb95c1e03bede218b8fb03bbd9ada9317))
-  *  linux uses open before anything else ([4696d1a5](https://github.com/Byron/open-rs/commit/4696d1a5ec80691e97bb1be4261d4f79ee0ade4d))
+  * use result ([25c0e398](https://github.com/Byron/open-rs/commit/25c0e398856c24a2daf0444640567ed3fd2f4307))
+  * don't use 'open' on linux ([30c96b1c](https://github.com/Byron/open-rs/commit/30c96b1cb95c1e03bede218b8fb03bbd9ada9317))
+  * linux uses open before anything else ([4696d1a5](https://github.com/Byron/open-rs/commit/4696d1a5ec80691e97bb1be4261d4f79ee0ade4d))
 * **rustup**  (07560d233 2015-04-20) (built 2015-04-19) ([8b4e1558](https://github.com/Byron/open-rs/commit/8b4e1558f09937c555ab381ea6399a2c0758c23d))
-
-
-

src/lib.rs

@@ -30,13 +30,13 @@
 //! ```
 
 #[cfg(target_os = "windows")]
-pub use windows::{that, with};
+use windows as os;
 
 #[cfg(target_os = "macos")]
-pub use macos::{that, with};
+use macos as os;
 
 #[cfg(target_os = "ios")]
-pub use ios::{that, with};
+use ios as os;
 
 #[cfg(any(
     target_os = "linux",
@@ -47,7 +47,7 @@ pub use ios::{that, with};
     target_os = "openbsd",
     target_os = "solaris"
 ))]
-pub use unix::{that, with};
+use unix as os;
 
 #[cfg(not(any(
     target_os = "linux",
@@ -72,13 +72,60 @@ use std::{
 
 type Result = io::Result<()>;
 
-/// Convenience function for opening the passed path in a new thread.
-/// See documentation of `that(...)` for more details.
+/// Open path with the default application.
+///
+/// # Examples
+///
+/// ```no_run
+/// let path = "http://rust-lang.org";
+///
+/// match open::that(path) {
+///     Ok(()) => println!("Opened '{}' successfully.", path),
+///     Err(err) => panic!("An error occurred when opening '{}': {}", path, err),
+/// }
+/// ```
+///
+/// # Errors
+///
+/// A [`std::io::Error`] is returned on failure. Because different operating systems
+/// handle errors differently it is recommend to not match on a certain error.
+pub fn that<T: AsRef<OsStr> + Sized>(path: T) -> Result {
+    os::that(path)
+}
+
+/// Open path with the given application.
+///
+/// # Examples
+///
+/// ```no_run
+/// let path = "http://rust-lang.org";
+/// let app = "firefox";
+///
+/// match open::with(path, app) {
+///     Ok(()) => println!("Opened '{}' successfully.", path),
+///     Err(err) => panic!("An error occurred when opening '{}': {}", path, err),
+/// }
+/// ```
+///
+/// # Errors
+///
+/// A [`std::io::Error`] is returned on failure. Because different operating systems
+/// handle errors differently it is recommend to not match on a certain error.
+pub fn with<T: AsRef<OsStr> + Sized>(path: T, app: impl Into<String>) -> Result {
+    os::with(path, app)
+}
+
+/// Open path with the default application in a new thread.
+///
+/// See documentation of [`that`] for more details.
 pub fn that_in_background<T: AsRef<OsStr> + Sized>(path: T) -> thread::JoinHandle<Result> {
     let path = path.as_ref().to_os_string();
     thread::spawn(|| that(path))
 }
 
+/// Open path with the given application in a new thread.
+///
+/// See documentation of [`with`] for more details.
 pub fn with_in_background<T: AsRef<OsStr> + Sized>(
     path: T,
     app: impl Into<String>,