From 0ad994d1fe116e4d3e35070331cbcb6a7ed11dc1 Mon Sep 17 00:00:00 2001
From: Armin Ronacher <armin.ronacher@active-4.com>
Date: Sun, 14 Jul 2019 21:21:18 +0200
Subject: [PATCH] Added readme to repository

---
 Cargo.toml |  2 ++
 Makefile   |  6 ++++++
 README.md  | 28 ++++++++++++++++++++++++++++
 src/lib.rs | 29 +++++++++++++++++++++++++----
 4 files changed, 61 insertions(+), 4 deletions(-)
 create mode 100644 README.md

diff --git a/Cargo.toml b/Cargo.toml
index 45dd903..c8b7805 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -7,9 +7,11 @@ license = "MIT/NCSA"
 documentation = "https://docs.rs/msvc-demangler/"
 description = "A rust library that demangles / undecorates C++ symbols mangled by MSVC"
 repository = "https://github.com/mstange/msvc-demangler-rust"
+readme = "README.md"
 
 [dependencies]
 bitflags = "1.0.1"
 
 [[bin]]
 name = "undname"
+path = "src/bin/undname.rs"
diff --git a/Makefile b/Makefile
index 8394b83..c143fe9 100644
--- a/Makefile
+++ b/Makefile
@@ -28,3 +28,9 @@ test: test-cargo test-wasm-build
 lint:
 	@rustup component add clippy --toolchain stable 2> /dev/null
 	@cargo +stable clippy --all --tests -- -D clippy::all
+.PHONY: lint
+
+update-readme:
+	@cargo-readme -V &> /dev/null || cargo install cargo-readme
+	@cargo readme > README.md
+.PHONY: update-readme
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..61057eb
--- /dev/null
+++ b/README.md
@@ -0,0 +1,28 @@
+# msvc-demangler
+
+msvc-demangler is a crate for Rust that can demangle C++ symbols which use
+the MSVC mangling scheme.  These are emitted by the Microsoft C++ compiler
+for Windows as well as some others.
+
+## Example
+
+```rust
+use msvc_demangler;
+let flags = msvc_demangler::DemangleFlags::llvm();
+let result = msvc_demangler::demangle("??_0klass@@QEAAHH@Z", flags).unwrap();
+println!("{}", result);
+```
+
+## Behavior
+
+It's functionality is similar to `undname` on Windows and the underlying
+`UnDecorateSymbolName` function.  Since Microsoft does not document the
+mangling scheme this is likely not to be entirely accurate.  When unclear
+the implementation tries to follow what LLVM does.
+
+## License
+
+This msvc-demangler is dual licensed under the MIT and the University of
+Illinois Open Source Licenses.
+
+License: MIT/NCSA
diff --git a/src/lib.rs b/src/lib.rs
index 7999483..d7190a3 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,7 +1,27 @@
-// This file is dual licensed under the MIT and the University of Illinois Open
-// Source Licenses. See LICENSE.TXT for details.
-//
-// This file defines a demangler for MSVC-style mangled symbols.
+//! msvc-demangler is a crate for Rust that can demangle C++ symbols which use
+//! the MSVC mangling scheme.  These are emitted by the Microsoft C++ compiler
+//! for Windows as well as some others.
+//!
+//! # Example
+//!
+//! ```
+//! use msvc_demangler;
+//! let flags = msvc_demangler::DemangleFlags::llvm();
+//! let result = msvc_demangler::demangle("??_0klass@@QEAAHH@Z", flags).unwrap();
+//! println!("{}", result);
+//! ```
+//!
+//! # Behavior
+//!
+//! It's functionality is similar to `undname` on Windows and the underlying
+//! `UnDecorateSymbolName` function.  Since Microsoft does not document the
+//! mangling scheme this is likely not to be entirely accurate.  When unclear
+//! the implementation tries to follow what LLVM does.
+//!
+//! # License
+//!
+//! This msvc-demangler is dual licensed under the MIT and the University of
+//! Illinois Open Source Licenses.
 
 #[macro_use]
 extern crate bitflags;
@@ -30,6 +50,7 @@ impl From<std::str::Utf8Error> for Error {
         }
     }
 }
+
 impl From<std::string::FromUtf8Error> for Error {
     fn from(t: std::string::FromUtf8Error) -> Error {
         Error {