docs: update documentation

* remove python references
* a bit more verbose README

Issue #7

README.md

@@ -1,3 +1,27 @@
+[![Build](https://travis-ci.org/mozilla-services/autopush-rs.svg?branch=master)](https://travis-ci.org/mozilla-services/autopush-rs)
+[![License: MPL 2.0]][MPL 2.0] [![Build Status]][travis]
+[![Latest Version]][crates.io] [![Api Rustdoc]][rustdoc]
+
 # Autopush-rs
 
-Mozilla Push server built with Rust.
+Mozilla Push server built with [Rust](https://rust-lang.org).
+
+This is the fourth generation of the Mozilla Web Push server. This is
+a "work in progress", that currently supports websocket connections
+and support for
+[Megaphone](https://github.com/mozilla-services/megaphone) broadcast.
+
+Please consult the [autopush
+documentation](http://autopush.readthedocs.io/en/latest/index.html)
+for information about how this server works, as well as any [error
+messages](http://autopush.readthedocs.io/en/latest/http.html#error-codes)
+you may see when sending push messages to our server.
+
+MDN has information about [how to use
+WebPush](https://developer.mozilla.org/en-US/docs/Web/API/Push_API)
+
+***Note*** while `rust-doc` style comments are used prolifically
+through the source, only pubic structures are rendered automatically.
+For those curious about the inner workings, You may wish to read the
+code files directly.
+

src/lib.rs

@@ -1,29 +1,14 @@
 //! WIP: Implementation of Web Push ("autopush" as well) in Rust
-//!
-//! This crate currently provides an implementation of an asynchronous Web Push
-//! server which is intended to be interfaced with from Python. The crate mostly
-//! has a C API which is driven from `__init__.py` in Python and orchestrated
-//! from Python. This is currently done to help ease the transition from the old
-//! Python implementation to the new Rust implementation. Currently there's a
-//! good bit of API calls to remote services still implemented in Python, but
-//! the thinking is that over time these services will be rewritten in to Rust
-//! and the Python codebase will shrink.
-//!
-//! In any case though, this'll focus mainly on the Rust bits rather than the
-//! Python bits! It's worth nothing though that this crate is intended to be
-//! used with `cffi` in Python, which is "seamlessly" worked with through the
-//! `snaek` Python dependency. That basically just means that Python "headers"
-//! for this Rust crate are generated automatically.
+//! 
+//! This crate currently provides the connection node functionality for a Web
+//! Push server, and is a replacement for the 
+//! [`autopush`](https://github.com/mozilla-services/autopush) server. The older
+//! python handler still manages the HTTP endpoint calls, since those require
+//! less overhead to process. Eventually, those functions will be moved to 
+//! rust as well.
 //!
 //! # High level overview
 //!
-//! At 10,000 feet the general architecture here is that the main Python thread
-//! spins up a Rust thread which actually does all the relevant I/O. The one
-//! Rust thread uses a `Core` from `tokio-core` to perform all I/O and schedule
-//! asynchronous tasks. The `tungstenite` crate is used to parse and manage the
-//! WebSocket protocol, with `tokio_tungstenite` being a nicer wrapper for
-//! futures-style APIs.
-//!
 //! The entire server is written in an asynchronous fashion using the `futures`
 //! crate in Rust. This basically just means that everything is exposed as a
 //! future (similar to the concept in other languages) and that's how bits and
@@ -33,10 +18,7 @@
 //! webpush protocol (see `states.dot` at the root of this repository). Note
 //! that not all states are implemented yet, this is a work in progress! All I/O
 //! is managed by Rust and various state transitions are managed by Rust as
-//! well. Movement between states happens typically as a result of calls into
-//! Python. The various operations here will call into Python to do things like
-//! db/HTTP requests and then the results are interpreted in Rust to progress
-//! the state machine.
+//! well. 
 //!
 //! # Module index
 //!

src/server/mod.rs

@@ -220,7 +220,7 @@ pub struct Server {
 }
 
 impl Server {
-    /// Creates a new server handle to send to python.
+    /// Creates a new server handle used by Megaphone and other services.
     ///
     /// This will spawn a new server with the `opts` specified, spinning up a
     /// separate thread for the tokio reactor. The returned ShutdownHandles can