docs: complete overhaul of the docs and the readme file

The previous docs were incomplete and weren't updated to fit the new
builder format the crate is using. Changes were needed.

Author: Ballasi

README.md

@@ -4,13 +4,46 @@
 
 Convert number like `42` to `forty-two`
 
+## Usage
+
+This crate can be either used as a library or a binary.
+
+### Library
+
 Example usage:
+
 ```rust
 use num2words::Num2Words;
 assert_eq!(Num2Words::new(42).to_words(), Ok(String::from("forty-two")));
 ```
 
-The app can also be run via a command-line interface.
+The builder Num2Words can take three arguments: `lang`, `output` and
+`currency`.
+
+```rust
+use num2words::*;
+assert_eq!(
+    Num2Words::new(42).lang(Lang::English).to_words(),
+    Ok(String::from("forty-two"))
+);
+assert_eq!(
+    Num2Words::new(42).output(Output::Ordinal).to_words(),
+    Ok(String::from("forty-second"))
+);
+assert_eq!(
+    Num2Words::new(42.01).currency(Currency::DOLLAR).to_words(),
+    Ok(String::from("forty-two dollars and one cent"))
+);
+```
+
+These arguments can be chained.
+
+For more information about the available languages, outputs and currencies,
+see [Informations](#informations).
+
+### Binary
+
+This crate provides a command-line interface to run requests on `num2words`.
 
 Example:
 ```sh
@@ -25,24 +58,63 @@ You can download the app via the following command:
 $ cargo install num2words
 ```
 
-For more information about the usage of `num2words` please refers to the
-docs or via the following command:
+You can also change the language via the argument `--lang` and provide an
+output or a currency with the argument `--to`.
+
+For more information about the usage of `num2words` please refer to the docs
+or via the following command:
 ```sh
 $ num2words --help
 ```
 
+## Informations
+
+### Supported languages
+
+Here is a list of all of the supported languages:
+
+| Flag | Code            | CLI code        | Language | 42        |
+| ---- | --------------- | --------------- | -------- | --------- |
+| 🇺🇸🇬🇧 | `Lang::English` | `en`            | English  | forty-two |
+
+This list can be expanded! Contributions are welcomed.
+
+### Supported output
+
+Here is a list of all of the supported outputs (with the command-line
+interface code):
+
+- `Output::Cardinal` (`cardinal`): forty-two (42)
+- `Output::Currency` (any available currencies): forty-two dollars and one
+   cent (42.01)
+- `Output::Ordinal` (`ordinal`): forty-second (42)
+- `Output::OrdinalNum` (`ordinal_num`): 42nd (42)
+- `Output::Year` (`year`): nineteen oh-one (1901)
+
+### Supported currencies
+
+Here is a list of all of the supported currencies (with the command-line
+interface code):
+
+- `Currency::AUD` (`AUD`): australian dollar
+- `Currency::CAD` (`CAD`): canadian dollar
+- `Currency::DOLLAR` (`DOLLAR`): dollar
+- `Currency::EUR` (`EUR`): euro
+- `Currency::GBP` (`GBP`): pound
+- `Currency::USD` (`USD`): US dollar
+
+### About
+
 This library is widely inspired by [Savoir-faire Linux's Python
 lib](https://github.com/savoirfairelinux/num2words/).
 
-**Warning**: this lib is not usable at its current state, we would recommend
-you come back later.
-
 ## License
 
 Licensed under either of
 
 - Apache License, Version 2.0
-  ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
+  ([LICENSE-APACHE](LICENSE-APACHE) or
+  http://www.apache.org/licenses/LICENSE-2.0)
 - MIT license
   ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
 
@@ -51,5 +123,5 @@ at your option.
 ## Contribution
 
 Unless you explicitly state otherwise, any contribution intentionally submitted
-for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
-dual licensed as above, without any additional terms or conditions.
+for inclusion in the work by you, as defined in the Apache-2.0 license,
+shall be dual licensed as above, without any additional terms or conditions.

src/lang/lang.rs

@@ -12,13 +12,27 @@ pub trait Language {
     fn to_currency(self, num: Number, currency: Currency) -> Result<String, Num2Err>;
 }
 
+/// Languages available in `num2words`
 pub enum Lang {
+    /// ```
+    /// use num2words::{Num2Words, Lang};
+    /// assert_eq!(
+    ///     Num2Words::new(42).lang(Lang::English).to_words(),
+    ///     Ok(String::from("forty-two"))
+    /// );
+    /// ```
     English,
 }
 
 impl FromStr for Lang {
     type Err = ();
 
+    /// Parses a string to return a value of this type
+    ///
+    ///
+    /// | &str | Lang            | 42        |
+    /// | ---- | --------------- | --------- |
+    /// | `en` | `Lang::English` | forty-two |
     fn from_str(input: &str) -> Result<Self, Self::Err> {
         match input {
             "en" => Ok(Self::English),

src/lib.rs

@@ -4,22 +4,109 @@
 /*!
  * Convert number like `42` to `forty-two`
  *
+ * ## Usage
+ *
+ * This crate can be either used as a library or a binary.
+ *
+ * ### Library
+ *
  * Example usage:
- * ```
+ *
+ * ```rust
  * use num2words::Num2Words;
  * assert_eq!(Num2Words::new(42).to_words(), Ok(String::from("forty-two")));
  * ```
  *
- * This lib will also be a downloadable binary in the near future.
+ * The builder Num2Words can take three arguments: `lang`, `output` and
+ * `currency`.
+ *
+ * ```rust
+ * use num2words::*;
+ * assert_eq!(
+ *     Num2Words::new(42).lang(Lang::English).to_words(),
+ *     Ok(String::from("forty-two"))
+ * );
+ * assert_eq!(
+ *     Num2Words::new(42).output(Output::Ordinal).to_words(),
+ *     Ok(String::from("forty-second"))
+ * );
+ * assert_eq!(
+ *     Num2Words::new(42.01).currency(Currency::DOLLAR).to_words(),
+ *     Ok(String::from("forty-two dollars and one cent"))
+ * );
+ * ```
+ *
+ * These arguments can be chained.
+ *
+ * For more information about the available languages, outputs and currencies,
+ * see [Informations](#informations).
+ *
+ * ### Binary
+ *
+ * This crate provides a command-line interface to run requests on `num2words`.
+ *
+ * Example:
+ * ```sh
+ * $ num2words 42
+ * forty-two
+ * $ num2words 10 --to EUR
+ * ten euros
+ * ```
+ *
+ * You can download the app via the following command:
+ * ```sh
+ * $ cargo install num2words
+ * ```
+ *
+ * You can also change the language via the argument `--lang` and provide an
+ * output or a currency with the argument `--to`.
+ *
+ * For more information about the usage of `num2words` please refer to the docs
+ * or via the following command:
+ * ```sh
+ * $ num2words --help
+ * ```
+ *
+ * ## Informations
+ *
+ * ### Supported languages
+ *
+ * Here is a list of all of the supported languages:
+ *
+ * | Flag | Code            | CLI code        | Language | 42        |
+ * | ---- | --------------- | --------------- | -------- | --------- |
+ * | 🇺🇸🇬🇧 | `Lang::English` | `en`            | English  | forty-two |
+ *
+ * This list can be expanded! Contributions are welcomed.
  *
- * For more detailed usage about the different parameters that you can give
- * to the macro, please take a look at [`num2words!`].
+ * ### Supported output
+ *
+ * Here is a list of all of the supported outputs (with the command-line
+ * interface code):
+ *
+ * - `Output::Cardinal` (`cardinal`): forty-two (42)
+ * - `Output::Currency` (any available currencies): forty-two dollars and one
+ *    cent (42.01)
+ * - `Output::Ordinal` (`ordinal`): forty-second (42)
+ * - `Output::OrdinalNum` (`ordinal_num`): 42nd (42)
+ * - `Output::Year` (`year`): nineteen oh-one (1901)
+ *
+ * ### Supported currencies
+ *
+ * Here is a list of all of the supported currencies (with the command-line
+ * interface code):
+ *
+ * - `Currency::AUD` (`AUD`): australian dollar
+ * - `Currency::CAD` (`CAD`): canadian dollar
+ * - `Currency::DOLLAR` (`DOLLAR`): dollar
+ * - `Currency::EUR` (`EUR`): euro
+ * - `Currency::GBP` (`GBP`): pound
+ * - `Currency::USD` (`USD`): US dollar
+ *
+ * ### About
  *
  * This library is widely inspired by [Savoir-faire Linux's Python
  * lib](https://github.com/savoirfairelinux/num2words/).
- *
- * **Warning**: this lib is not usable at its current state, we would recommend
- * you come back later.
  */
 mod num2words;
 mod currency;