Improve crate documentation

src/lib.rs

@@ -1,3 +1,54 @@
+//! This is an extension to chrono's date and time formatting to automatically translate
+//! dates to a specified locale or language
+//!
+//! ## Usage
+//!
+//! Put this in your Cargo.toml:
+//!
+//! ```
+//! [dependencies]
+//! chrono = "0.4"
+//! chrono_locale = "0.1"
+//! ```
+//!
+//! Then put this in your `lib.rs` or `main.rs`:
+//!
+//! ```
+//! extern crate chrono;
+//! extern crate chrono_locale;
+//!
+//! use chrono::prelude::*;
+//! use chrono_locale::LocaleDate;
+//! ```
+//!
+//! You can choose to import just parts of chrono instead of the whole prelude.
+//! Please see ['chrono`'s documentation](https://docs.rs/chrono/).
+//!
+//! To format a chrono `Date` or `DateTime` object, you can use the `formatl` method:
+//!
+//! ```
+//! let dt = FixedOffset::east(34200).ymd(2001, 7, 8).and_hms_nano(0, 34, 59, 1_026_490_708);
+//! println!("{}", dt.formatl("%c", "fr"));
+//! ```
+//!
+//! All of [chrono's formatting placeholders](https://docs.rs/chrono/0.4.6/chrono/format/strftime/index.html)
+//! work except for `%3f`, `%6f` and `%9f` (but `%.3f`, `%.6f` and `%.9f` work normally)
+//!
+//! ## Locale format
+//!
+//! The `formatl` method supports locales in different formats, based on ISO-639-1 and ISO-3166.
+//! It accepts any format where they are separated by `-` or `_`:
+//!
+//! - en_GB
+//! - it-IT
+//! - fr-fr
+//! - PT_br
+//!
+//! The translated string will be first searched in the complete locale definition, then in the fallbacks.
+//! For example: by requesting `it_IT` it will first try in `it-it`, then in `it` and, if it still
+//! doesn't find it, it will use the default: `C` (english)
+//!
+
 #[macro_use]
 extern crate lazy_static;
 extern crate chrono;