diff --git a/README b/README
deleted file mode 100644
index 0a4cc54..0000000
--- a/README
+++ /dev/null
@@ -1,10 +0,0 @@
-Pure bindings to libclang
-=========================
-
-A Haskell library for pure C++ code analysis with some light `lens` support.
-
-```
-gotoCount = lengthOf (allNodes . filtered (\c -> cursorKind c == GotoStmt)) root
-```
-
-*This is not an official Google product (experimental or otherwise), it is just code that happens to be owned by Google.*
\ No newline at end of file
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..6e8c72b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,31 @@
+# Pure Haskell bindings to [libclang]
+
+A Haskell library for pure C++ code analysis with some light `lens` support
+
+## API examples
+
+### Get count of `goto` statements in program
+
+```haskell
+gotoCount = lengthOf (allNodes . filtered (\c -> cursorKind c == GotoStmt)) root
+```
+
+### Enumerate all function declarations in `main.cpp`
+
+```haskell
+module Main (main) where
+
+import Control.Monad
+import Language.C.Clang
+
+main :: IO ()
+main = do
+    idx <- createIndex
+    tu <- parseTranslationUnit idx "main.cpp" ["-I/usr/local/include"]
+    let root = translationUnitCursor tu
+        children = cursorChildren root
+        functionDecls = filter (\c -> cursorKind c == FunctionDecl) children
+    forM_ functionDecls $ \f -> print $ cursorSpelling f
+```
+
+[libclang]: http://clang.llvm.org/doxygen/group__CINDEX.html