diff --git a/src/lib.rs b/src/lib.rs
index dc1ec02..fa8093d 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -15,6 +15,40 @@
 // along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
 //! A small library for selecting the best match for user's preferred locales from available locales.
+//!
+//! The library consists of two modules:
+//! * `bcp47` - for matching locales in the [BCP 47](https://www.ietf.org/rfc/bcp/bcp47.html) format
+//! * `posix` - for matching locales in the [POSIX](https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap08.html) format
+//!
+//! Both modules provide the `best_matching_locale` function.
+//! 
+//! ## Examples
+//! 
+//! ### BCP 47
+//!
+//! ```
+//! use locale_match::bcp47::best_matching_locale;
+//!
+//! let available_locales = ["en-US", "ru-BY"];
+//! let user_locales = ["ru-RU", "ru", "en-US", "en"];
+//!
+//! let best_match = best_matching_locale(available_locales, user_locales);
+//!
+//! assert_eq!(best_match, Some("ru-BY"));
+//! ```
+//! 
+//! ### POSIX
+//! 
+//! ```
+//! use locale_match::posix::best_matching_locale;
+//!
+//! let available_locales = ["en_US.UTF-8", "ru_BY.UTF-8"];
+//! let user_locales = ["ru_RU.UTF-8", "ru", "en_US.UTF-8", "en"];
+//! 
+//! let best_match = best_matching_locale(available_locales, user_locales);
+//! 
+//! assert_eq!(best_match, Some("ru_BY.UTF-8"));
+//! ```
 
 #[cfg(feature = "bcp47")]
 pub mod bcp47;