Add try_fn to the crate docs + minor doc cleanups

Author: Nemo157

src/lib.rs

@@ -1,19 +1,25 @@
 #![no_std]
 
-//! Annotations a function that "throws" a Result.
+//! Annotates a function that "throws" a Result.
 //!
-//! Inside functions tagged with `throws`, you can use `?` and the `throw!` macro to return errors,
-//! but you don't need to wrap the successful return values in `Ok`.
+//! Inside functions tagged with either `throws` or `try_fn`, you can use `?` and the `throw!`
+//! macro to return errors, but you don't need to wrap the successful return values in `Ok`.
 //!
-//! Using this syntax, you can write fallible functions almost as if they were nonfallible. Every
+//! Using this syntax, you can write fallible functions almost as if they were infallible. Every
 //! time a function call would return a `Result`, you "re-raise" the error using `?`, and if you
 //! wish to raise your own error, you can return it with the `throw!` macro.
 //!
+//! The difference between `throws` and `try_fn` is in the function signature, with `throws` you
+//! write the signature as if it were infallible too, it will be transformed into a `Result` for
+//! you. With `try_fn` you write the signature as normal and only the body of the function will be
+//! transformed.
+//!
 //! ## Example
+//!
 //! ```
 //! use std::io::{self, Read};
 //!
-//! use culpa::{throw, throws};
+//! use culpa::{throw, throws, try_fn};
 //!
 //! #[throws(io::Error)]
 //! fn check() {
@@ -27,13 +33,26 @@
 //!
 //!     println!("Okay!");
 //! }
+//!
+//! #[try_fn]
+//! fn check_as_try_fn() -> std::io::Result<()> {
+//!     let mut file = std::fs::File::open("The_House_of_the_Spirits.txt")?;
+//!     let mut text = String::new();
+//!     file.read_to_string(&mut text)?;
+//!
+//!     if !text.starts_with("Barrabas came to us by sea, the child Clara wrote") {
+//!         throw!(io::Error::from_raw_os_error(22));
+//!     }
+//!
+//!     println!("Okay!");
+//! }
 //! ```
 //!
-//! # Default Error Type
+//! # `throws` Default Error Type
 //!
-//! This macro supports a "default error type" - if you do not pass a type to the macro, it will
-//! use the type named `Error` in this scope. So if you have defined an error type in this
-//! module, that will be the error thrown by this function.
+//! The `throws` macro supports a "default error type" - if you do not pass a type to the macro, it
+//! will use the type named `Error` in the current scope. So if you have defined an error type in
+//! the module, that will be the error thrown by this function.
 //!
 //! You can access this feature by omitting the arguments entirely or by passing `_` as the type.
 //!
@@ -43,7 +62,7 @@
 //! use culpa::throws;
 //!
 //! // Set the default error type for this module:
-//! type Error = std::io::Error;
+//! use std::io::Error;
 //!
 //! #[throws]
 //! fn print() {
@@ -54,21 +73,28 @@
 //!
 //! # Throwing as an Option
 //!
-//! This syntax can also support functions which return an `Option` instead of a `Result`. The
-//! way to access this is to pass `as Option` as the argument to `throw`.
+//! This syntax can also support functions which return an `Option` instead of a `Result`. To use
+//! this with `throws` pass `as Option` as the argument in place of the error type, to use it with
+//! `try_fn` just put it as the return type like normal
 //!
 //! In functions that return `Option`, you can use the `throw!()` macro without any argument to
 //! return `None`.
 //!
 //! ## Example
 //!
 //! ```
-//! use culpa::{throw, throws};
-//!
-//! #[throws(as Option)]
+//! #[culpa::throws(as Option)]
 //! fn example<T: Eq + Ord>(slice: &[T], needle: &T) -> usize {
 //!     if !slice.contains(needle) {
-//!         throw!();
+//!         culpa::throw!();
+//!     }
+//!     slice.binary_search(needle).ok()?
+//! }
+//!
+//! #[culpa::try_fn]
+//! fn example_as_try_fn<T: Eq + Ord>(slice: &[T], needle: &T) -> Option<usize> {
+//!     if !slice.contains(needle) {
+//!         culpa::throw!();
 //!     }
 //!     slice.binary_search(needle).ok()?
 //! }
@@ -78,15 +104,15 @@
 //!
 //! The `?` syntax in Rust is controlled by a trait called `Try`, which is currently unstable.
 //! Because this feature is unstable and I don't want to maintain compatibility if its interface
-//! changes, this crate currently only works with two stable `Try` types: Result and Option.
+//! changes, this crate currently only works with two stable `Try` types: `Result` and `Option`.
 //! However, its designed so that it will hopefully support other `Try` types as well in the
 //! future.
 //!
 //! It's worth noting that `Try` also has some other stable implementations: specifically `Poll`.
 //! Because of the somewhat unusual implementation of `Try` for those types, this crate does not
 //! support `throws` syntax on functions that return `Poll` (so you can't use this syntax when
-//! implementing a Future by hand, for example). I hope to come up with a way to support Poll in
-//! the future.
+//! implementing a `Future` by hand, for example). I hope to come up with a way to support `Poll`
+//! in the future.
 
 #[doc(inline)]
 /// Annotates a function that "throws" a Result.