Add documentation (Rust)

1 files changed, 55 insertions, 0 deletions

diff --git a/src/lib.rs b/src/lib.rs
index 377310f..4c4a31c 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,3 +1,58 @@
+//! This crate implements [IETF RFC 3986](https://tools.ietf.org/html/rfc3986),
+//! "Uniform Resource Identifier (URI): Generic Syntax".  The [`Uri`] type
+//! can be used to parse and generate RFC-conformant URI strings to and from
+//! their various components.
+//!
+//! A Uniform Resource Identifier (URI) is a compact sequence of characters
+//! that identifies an abstract or physical resource.  One common form of URI
+//! is the Uniform Resource Locator (URL), used to reference web resources:
+//!
+//! ```text
+//! http://www.example.com/foo?bar#baz
+//! ```
+//!
+//! Another kind of URI is the path reference:
+//!
+//! ```text
+//! /usr/bin/zip
+//! ```
+//!
+//! # Examples
+//!
+//! ## Parsing a URI into its components
+//!
+//! ```rust
+//! # extern crate uri;
+//! use uri::Uri;
+//!
+//! let uri = Uri::parse("http://www.example.com/foo?bar#baz").unwrap();
+//! let authority = uri.authority().unwrap();
+//! assert_eq!("www.example.com".as_bytes(), authority.host());
+//! assert_eq!(Some("www.example.com"), uri.host_as_string().unwrap().as_deref());
+//! assert_eq!("/foo", uri.path_as_string().unwrap());
+//! assert_eq!(Some("bar"), uri.query_as_string().unwrap().as_deref());
+//! assert_eq!(Some("baz"), uri.fragment_as_string().unwrap().as_deref());
+//! ```
+//!
+//! ## Generating a URI from its components
+//!
+//! ```rust
+//! # extern crate uri;
+//! use uri::{Authority, Uri};
+//!
+//! let mut uri = Uri::default();
+//! assert!(uri.set_scheme(String::from("http")).is_ok());
+//! let mut authority = Authority::default();
+//! authority.set_host("www.example.com");
+//! uri.set_authority(Some(authority));
+//! uri.set_path_from_str("/foo");
+//! uri.set_query(Some("bar".into()));
+//! uri.set_fragment(Some("baz".into()));
+//! assert_eq!("http://www.example.com/foo?bar#baz", uri.to_string());
+//! ```
+//!
+//! [`Uri`]: struct.Uri.html
+
 #![warn(clippy::pedantic)]
 #![allow(clippy::non_ascii_literal)]
 #![warn(missing_docs)]