Documentation updates

Author: sfackler

README.md

@@ -179,8 +179,7 @@ A very basic fixed-size connection pool is provided in the `pool` module. A
 single pool can be shared across tasks and `get_connection` will block until a
 connection is available.
 ```rust
-let pool = PostgresConnectionPool::new("postgres://postgres@localhost", 5)
-        .unwrap();
+let pool = PostgresConnectionPool::new("postgres://postgres@localhost", 5);
 
 for _ in range(0, 10) {
     do task::spawn_with(pool.clone()) |pool| {

src/postgres/lib.rs

@@ -1,3 +1,56 @@
+/*!
+Rust-Postgres is a pure-Rust frontend for the popular PostgreSQL database. It
+exposes a high level interface in the vein of JDBC or Go's `database/sql`
+package.
+
+```rust
+extern mod postgres;
+
+use postgres::PostgresConnection;
+use postgres::types::ToSql;
+
+#[deriving(ToStr)]
+struct Person {
+    id: i32,
+    name: ~str,
+    awesome: bool,
+    data: Option<~[u8]>
+}
+
+fn main() {
+    let conn = PostgresConnection::connect("postgres://postgres@localhost");
+
+    conn.update("CREATE TABLE person (
+                    id      SERIAL PRIMARY KEY,
+                    name    VARCHAR NOT NULL,
+                    awesome BOOL NOT NULL,
+                    data    BYTEA
+                 )", []);
+    let me = Person {
+        id: 0,
+        name: ~"Steven",
+        awesome: true,
+        data: None
+    };
+    conn.update("INSERT INTO person (name, awesome, data)
+                    VALUES ($1, $2, $3)",
+                 [&me.name as &ToSql, &me.awesome as &ToSql,
+                  &me.data as &ToSql]);
+
+    let stmt = conn.prepare("SELECT id, name, awesome, data FROM person");
+    for row in stmt.query([]) {
+        let person = Person {
+            id: row[0],
+            name: row[1],
+            awesome: row[2],
+            data: row[3]
+        };
+        println!("Found person {}", person.to_str());
+    }
+}
+```
+ */
+
 #[desc="A native PostgreSQL driver"];
 #[license="MIT"];