diff --git a/src/lib.rs b/src/lib.rs
index 2344f36..ac166d5 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,3 +1,52 @@
+/*!
+This crate allows one to parse PromQL query into some AST.
+
+See [official documentation](https://prometheus.io/docs/prometheus/latest/querying/basics/) for query syntax description.
+
+## Example
+
+```
+# extern crate nom;
+# extern crate promql;
+# fn main() {
+
+use promql::*;
+
+let ast = parse(b"
+	sum(1 - something_used{env=\"production\"} / something_total) by (instance)
+	and ignoring (instance)
+	sum(rate(some_queries{instance=~\"localhost\\\\d+\"} [5m])) > 100
+").unwrap(); // or show user that their query is invalid
+
+// now we can look for all sorts of things
+
+// AST can represent an operator
+if let Node::Operator { x, op: Op::And(op_mod), y } = ast {
+	// operators can have modifiers
+	assert_eq!(op_mod, Some(OpMod {
+		action: OpModAction::Ignore,
+		labels: vec!["instance".to_string()],
+		group: None,
+	}));
+
+	// aggregation functions like sum are represented as functions with optional modifiers (`by (label1, …)`/`without (…)`)
+	if let Node::Function { ref name, ref aggregation, ref args } = *x {
+		assert_eq!(*name, "sum".to_string());
+		assert_eq!(*aggregation, Some(AggregationMod {
+			action: AggregationAction::By,
+			labels: vec!["instance".to_string()],
+		}));
+
+		// …
+	}
+} else {
+	panic!("top operator is not an \"and\"");
+}
+
+# }
+```
+*/
+
 #[macro_use]
 extern crate nom;
 #[macro_use]