Use README.md for the crate docs, and rewrite it.

README.md

@@ -2,13 +2,81 @@
 # curve25519-dalek  [![](https://img.shields.io/crates/v/curve25519-dalek.svg)](https://crates.io/crates/curve25519-dalek) [![](https://docs.rs/curve25519-dalek/badge.svg)](https://docs.rs/curve25519-dalek) [![](https://travis-ci.org/dalek-cryptography/curve25519-dalek.svg?branch=master)](https://travis-ci.org/dalek-cryptography/curve25519-dalek)
 
 <img
- width="50%"
+ width="33%"
  align="right"
  src="https://user-images.githubusercontent.com/797/34898472-83686016-f7f3-11e7-967b-24b2aadd623a.png"/>
 
-**A low-level cryptographic library for point, group, field, and scalar
+**A pure-Rust implementation of group operations on Ristretto and Curve25519.**
-operations on a curve isomorphic to the twisted Edwards curve defined by -x²+y²
+
-= 1 - 121665/121666 x²y² over GF(2²⁵⁵ - 19).**
+`curve25519-dalek` is a library providing group operations on the Edwards and
+Montgomery forms of Curve25519, and on the prime-order Ristretto group.
+
+`curve25519-dalek` is not intended to provide implementations of any particular
+crypto protocol.  Rather, implementations of those protocols (such as
+[`x25519-dalek`][x25519-dalek] and [`ed25519-dalek`][ed25519-dalek]) should use
+`curve25519-dalek` as a library.
+
+`curve25519-dalek` is intended to provide a clean and safe _mid-level_ API for use
+implementing a wide range of ECC-based crypto protocols, such as key agreement,
+signatures, anonymous credentials, rangeproofs, and zero-knowledge proof
+systems.
+
+## WARNING
+
+We do not yet consider this code to be production-ready.  We intend to
+stabilize a production-ready version `1.0` soon.
+
+# Documentation
+
+The semver-stable, public-facing `curve25519-dalek` API is documented
+[here][docs-external].  In addition, the unstable internal implementation
+details are documented [here][docs-internal].
+
+The `curve25519-dalek` documentation requires a custom HTML header to include
+KaTeX for math support. Unfortunately `cargo doc` does not currently support
+this, but docs can be built using
+```sh
+make doc
+make doc-internal
+```
+
+# Use
+
+To import `curve25519-dalek`, add the following to the dependencies section of
+your project's `Cargo.toml`:
+```toml
+curve25519-dalek = "^0.14"
+```
+Then import the crate as:
+```rust,no_run
+extern crate curve25519_dalek;
+```
+
+# Backends and Features
+
+Curve arithmetic is implemented using one of the following backends:
+
+* a `u32` backend using `u64` products;
+* a `u64` backend using `u128` products, available using the `nightly` feature;
+* an experimental AVX2 backend, available using the `yolocrypto` feature when compiling for a target with `target_feature=+avx2`
+
+By default, the benchmarks are not compiled without the `bench`
+feature.  Benchmarks can be run via:
+
+```sh
+cargo bench --features="bench"                    # u32 backend
+cargo bench --features="bench nightly"            # u64 backend
+cargo bench --features="bench nightly yolocrypto" # u64 or avx2 if available
+```
+
+# Contributing
+
+Please see [CONTRIBUTING.md][contributing].
+
+Patches and pull requests should be make against the `develop`
+branch, **not** `master`.
+
+# About
 
 **SPOILER ALERT:** *The Twelfth Doctor's first encounter with the Daleks is in
 his second full episode, "Into the Dalek". A beleaguered ship of the "Combined
@@ -23,65 +91,16 @@ universe's beauty, but also his deep hatred of the Daleks. Rusty destroys the
 other Daleks and departs the ship, determined to track down and bring an end
 to the Dalek race.*
 
-Significant portions of this code are ported from [Adam Langley's
+`curve25519-dalek` is authored by Isis Agora Lovecruft and Henry de Valence. 
-Golang ed25519 library](https://github.com/agl/ed25519), which is in
+
+Portions of this library were originally a port of [Adam Langley's
+Golang ed25519 library](https://github.com/agl/ed25519), which was in
 turn a port of the reference `ref10` implementation.
 
-## Warning
+The fast `u32` and `u64` scalar arithmetic was implemented by Andrew Moon, and
+the addition chain for scalar inversion was provided by Brian Smith.  The
+`no_std` support was contributed by Tony Arcieri.
 
-This code has **not** yet received sufficient peer review by other qualified
+[ed25519-dalek]: https://github.com/dalek-cryptography/ed25519-dalek
-cryptographers to be considered in any way, shape, or form, safe.  Further,
+[x25519-dalek]: https://github.com/dalek-cryptography/x25519-dalek
-this library does **not** provide high-level routines such as encryption and
+[contributing]: https://github.com/dalek-cryptography/curve25519-dalek/blob/master/CONTRIBUTING.md
-decryption or signing and verification.  Instead, it is a low-level library,
-intended for other cryptographers who would like to implement their own
-primitives using this curve.  (For an example of how one would implement a
-signature scheme using this library, see
-[ed25519-dalek](https://github.com/dalek-cryptography/ed25519-dalek).)
-
-**USE AT YOUR OWN RISK**
-
-## Documentation
-
-Extensive documentation is available [here](https://docs.rs/curve25519-dalek).
-
-# Installation
-
-To install, add the following to the dependencies section of your project's
-`Cargo.toml`:
-
-```toml
-curve25519-dalek = "^0.14"
-```
-
-Then, in your library or executable source, add:
-
-    extern crate curve25519_dalek;
-
-## Features
-
-On nightly Rust, using the `nightly` feature enables a radix-51 field
-arithmetic implementation using `u128`s, which is approximately twice as
-fast.  It will also enable additional developer documentation when
-compiling via `make doc-internal`.
-
-By default, the benchmarks are not compiled without the `bench`
-feature.  To run the benchmarks, do:
-
-```sh
-cargo bench --features="bench"
-```
-
-## TODO
-
-We intend to stabilise the following before curve25519-dalek-1.0.0:
-
-* Implement hashing to a point on the curve (Elligator).
-* Finish Ristretto documentation.
-
-## Contributing
-
-Please see
-[CONTRIBUTING.md](https://github.com/dalek-cryptography/curve25519-dalek/blob/master/CONTRIBUTING.md).
-
-Patches and pull requests should be make against the `develop`
-branch, **not** `master`.

src/lib.rs

@@ -9,29 +9,21 @@
 // - Henry de Valence <hdevalence@hdevalence.ca>
 
 #![cfg_attr(not(feature = "std"), no_std)]
+
 #![cfg_attr(feature = "alloc", feature(alloc))]
-#![cfg_attr(feature = "nightly", feature(i128_type))]
-#![cfg_attr(feature = "nightly", feature(cfg_target_feature))]
 #![cfg_attr(feature = "bench", feature(test))]
 
-#![deny(missing_docs)] // refuse to compile if documentation is missing
+#![cfg_attr(feature = "nightly", feature(i128_type))]
+#![cfg_attr(feature = "nightly", feature(cfg_target_feature))]
+#![cfg_attr(feature = "nightly", feature(external_doc))]
 
-//! # curve25519-dalek
+// Refuse to compile if documentation is missing, but only on nightly.
-//!
+//
-//! **A high-performance, pure-Rust implementation of group operations for Ristretto and Curve25519.**
+// This means that missing docs will still fail CI, but means we can use
-//!
+// README.md as the crate documentation.
-//! **[SPOILER ALERT]** The Twelfth Doctor's first encounter with the Daleks is
+#![cfg_attr(feature = "nightly", deny(missing_docs))]
-//! in his second full episode, "Into the Dalek".  A beleaguered ship of the
+
-//! "Combined Galactic Resistance" has discovered a broken Dalek that has
+#![cfg_attr(feature = "nightly", doc(include = "../README.md"))]
-//! turned "good", desiring to kill all other Daleks.  The Doctor, Clara and a
-//! team of soldiers are miniaturized and enter the Dalek, which the Doctor
-//! names Rusty.  They repair the damage, but accidentally restore it to its
-//! original nature, causing it to go on the rampage and alert the Dalek fleet
-//! to the whereabouts of the rebel ship.  However, the Doctor manages to
-//! return Rusty to its previous state by linking his mind with the Dalek's:
-//! Rusty shares the Doctor's view of the universe's beauty, but also his deep
-//! hatred of the Daleks.  Rusty destroys the other Daleks and departs the
-//! ship, determined to track down and bring an end to the Dalek race.
 
 //------------------------------------------------------------------------
 // External dependencies: