Merge pull request #342 from paupino/feature/docs

Update documentation

README.md

@@ -4,6 +4,7 @@
 [actions]: https://actions-badge.atrox.dev/paupino/rust-decimal/goto
 [Latest Version]: https://img.shields.io/crates/v/rust-decimal.svg
 [crates.io]: https://crates.io/crates/rust-decimal
+[![Documentation](https://docs.rs/rust_decimal/badge.svg)](https://docs.rs/rust_decimal)
 
 A Decimal implementation written in pure Rust suitable for financial calculations that require significant integral and fractional digits with no round-off errors.
 
@@ -30,16 +31,16 @@ Alternatively you can also use one of the Decimal number convenience functions:
 use rust_decimal::prelude::*;
 
 // Using an integer followed by the decimal points
-let scaled = Decimal::new(202, 2); // 2.02
+let scaled = Decimal::new(202, 2);
 assert_eq!("2.02", scaled.to_string());
 
 // From a string representation
-let from_string = Decimal::from_str("2.02").unwrap(); // 2.02
+let from_string = Decimal::from_str("2.02").unwrap();
 assert_eq!("2.02", from_string.to_string());
 
 // From a string representation in a different base
-let from_string_base16 = Decimal::from_str_radix("ffff.ff", 16).unwrap(); // 2.02
-assert_eq!("2.02", from_string_base16.to_string());
+let from_string_base16 = Decimal::from_str_radix("ffff", 16).unwrap();
+assert_eq!("65535", from_string_base16.to_string());
 
 // Using the `Into` trait
 let my_int: Decimal = 3i32.into();
@@ -93,7 +94,7 @@ Enable `rust-fuzz` support by implementing the `Arbitrary` trait.
 Enable this so that JSON serialization of Decimal types are sent as a float instead of a string (default).
 
 e.g. with this turned on, JSON serialization would output:
-```
+```json
 {
   "value": 1.234
 }

src/lib.rs

@@ -11,29 +11,118 @@
 //!
 //! ## Usage
 //!
-//! Decimal numbers can be created in a few distinct ways, depending
-//! on the rust compiler version you're targeting.
+//! Decimal numbers can be created in a few distinct ways. The easiest and most optimal
+//! method of creating a Decimal is to use the procedural macro within the
+//! `rust_decimal_macros` crate:
 //!
-//! The stable version of rust requires you to create a Decimal number
-//! using one of it's convenience methods.
+//! ```ignore
+//! // Procedural macros need importing directly
+//! use rust_decimal_macros::dec;
+//!
+//! let number = dec!(-1.23);
+//! assert_eq!("-1.23", number.to_string());
+//! ```
+//!
+//! Alternatively you can also use one of the Decimal number convenience functions:
 //!
 //! ```rust
+//! // Using the prelude can help importing trait based functions (e.g. core::str::FromStr).
 //! use rust_decimal::prelude::*;
 //!
 //! // Using an integer followed by the decimal points
-//! let scaled = Decimal::new(202, 2); // 2.02
+//! let scaled = Decimal::new(202, 2);
+//! assert_eq!("2.02", scaled.to_string());
 //!
 //! // From a string representation
-//! let from_string = Decimal::from_str("2.02").unwrap(); // 2.02
+//! let from_string = Decimal::from_str("2.02").unwrap();
+//! assert_eq!("2.02", from_string.to_string());
+//!
+//! // From a string representation in a different base
+//! let from_string_base16 = Decimal::from_str_radix("ffff", 16).unwrap();
+//! assert_eq!("65535", from_string_base16.to_string());
 //!
 //! // Using the `Into` trait
-//! let my_int : Decimal = 3i32.into();
+//! let my_int: Decimal = 3i32.into();
+//! assert_eq!("3", my_int.to_string());
 //!
 //! // Using the raw decimal representation
-//! // 3.1415926535897932384626433832
 //! let pi = Decimal::from_parts(1102470952, 185874565, 1703060790, false, 28);
+//! assert_eq!("3.1415926535897932384626433832", pi.to_string());
 //! ```
 //!
+//! ## Features
+//!
+//! * [db-postgres](#db-postgres)
+//! * [db-tokio-postgres](#db-tokio-postgres)
+//! * [db-diesel-postgres](#db-diesel-postgres)
+//! * [legacy-ops](#legacy-ops)
+//! * [maths](#maths)
+//! * [rust-fuzz](#rust-fuzz)
+//! * [serde-float](#serde-float)
+//! * [serde-str](#serde-str)
+//! * [std](#std)
+//!
+//! ## `db-postgres`
+//!
+//! This feature enables a PostgreSQL communication module. It allows for reading and writing the `Decimal`
+//! type by transparently serializing/deserializing into the `NUMERIC` data type within PostgreSQL.
+//!
+//! ## `db-tokio-postgres`
+//!
+//! Enables the tokio postgres module allowing for async communication with PostgreSQL.
+//!
+//! ## `db-diesel-postgres`
+//!
+//! Enable `diesel` PostgreSQL support.
+//!
+//! ## `legacy-ops`
+//!
+//! As of `1.10` the algorithms used to perform basic operations have changed which has benefits of significant speed improvements.
+//! To maintain backwards compatibility this can be opted out of by enabling the `legacy-ops` feature.
+//!
+//! ## `maths`
+//!
+//! This feature enables mathematical functionality such as `pow`, `ln`, `enf` etc.
+//!
+//! ## `rust-fuzz`
+//!
+//! Enable `rust-fuzz` support by implementing the `Arbitrary` trait.
+//!
+//! ## `serde-float`
+//!
+//! Enable this so that JSON serialization of Decimal types are sent as a float instead of a string (default).
+//!
+//! e.g. with this turned on, JSON serialization would output:
+//! ```json
+//! {
+//!   "value": 1.234
+//! }
+//! ```
+//!
+//! ## `serde-str`
+//!
+//! This is typically useful for `bincode` or `csv` like implementations.
+//!
+//! Since `bincode` does not specify type information, we need to ensure that a type hint is provided in order to
+//! correctly be able to deserialize. Enabling this feature on it's own will force deserialization to use `deserialize_str`
+//! instead of `deserialize_any`.
+//!
+//! If, for some reason, you also have `serde-float` enabled then this will use `deserialize_f64` as a type hint. Because
+//! converting to `f64` _loses_ precision, it's highly recommended that you do NOT enable this feature when working with
+//! `bincode`. That being said, this will only use 8 bytes so is slightly more efficient in regards to storage size.
+//!
+//! ## `serde-arbitrary-precision`
+//!
+//! This is used primarily with `serde_json` and consequently adds it as a "weak dependency". This supports the
+//! `arbitrary_precision` feature inside `serde_json` when parsing decimals.
+//!
+//! This is recommended when parsing "float" looking data as it will prevent data loss.
+//!
+//! ## `std`
+//!
+//! Enable `std` library support. This is enabled by default, however in the future will be opt in. For now, to support `no_std`
+//! libraries, this crate can be compiled with `--no-default-features`.
+//!
 #![forbid(unsafe_code)]
 #![cfg_attr(not(feature = "std"), no_std)]
 extern crate alloc;