docs: flesh out API docs

Author: soedirgo

README.md

@@ -1,22 +1,27 @@
-# postgrest-rs 🦀
+# postgrest-rs
 
-[![build](https://github.com/supabase/postgrest-rs/workflows/CI/badge.svg)](https://github.com/supabase/postgrest-rs/actions?query=branch%3Amaster)
+[![Build](https://github.com/supabase/postgrest-rs/workflows/CI/badge.svg)](https://github.com/supabase/postgrest-rs/actions?query=branch%3Amaster)
+[![Crate](https://img.shields.io/crates/v/postgrest.svg)](https://crates.io/crates/postgrest)
+[![API](https://docs.rs/postgrest/badge.svg)](https://docs.rs/postgrest)
 [![License: Apache-2.0 OR MIT](https://img.shields.io/crates/l/postgrest.svg)](#license)
 
-[PostgREST](https://postgrest.org/) client-side library (Rust edition). This library aims to reach feature parity with [postgrest-js](https://github.com/supabase/postgrest-js) in providing an "ORM-like" RESTful interface.
+[PostgREST](https://postgrest.org/) client-side library 🦀. This library provides an ORM interface to PostgREST.
 
 ## Usage
 
-Generally, you want to instantiate a `Postgrest` struct, optionally switch
-schema with `.schema()`, call `.from()` (or `.rpc()` for stored procedures), do
-some filtering and stuff, and then call `.execute()`.
+Add this to your `Cargo.toml`:
+
+```toml
+[dependencies]
+postgrest = "1.0"
+```
 
 Simple example:
 
 ```rust
 use postgrest::Postgrest;
 
-let client = Postgrest::new("https://your-postgrest-endpoint");
+let client = Postgrest::new("https://your.postgrest.endpoint");
 let resp = client
     .from("your_table")
     .select("*")
@@ -64,54 +69,42 @@ _Not enough filters_:
 ```rust
 let resp = client
     .from("countries")
-    .eq("name", "New Zealand")
+    .eq("name", "New Zealand")                        // You can filter for equality...
     .gt("id", "20")
     .lt("id", "20")
     .gte("id", "20")
     .lte("id", "20")
-    .like("name", "%United%")
+    .like("name", "%United%")                         // ...do pattern matching...
     .ilike("name", "%United%")
     .is("name", "null")
     .in_("name", vec!["China", "France"])
     .neq("name", "China")
-    .fts("phrase", "The Fat Cats", Some("english"))
+    .fts("phrase", "The Fat Cats", Some("english"))   // ...do full text search...
     .plfts("phrase", "The Fat Cats", None)
     .phfts("phrase", "The Fat Cats", Some("english"))
     .wfts("phrase", "The Fat Cats", None)
     .cs("countries", "(10,20)")
     .cd("countries", "(10,20)")
     .ov("population_range", (100, 500))
-    .sl("population_range", (100, 500))
-    .sr("population_range", (100, 500))
-    .nxl("population_range", (100, 500))
+    .sl("population_range", (100, 500))               // ...and range operations!
+    .sr("population_range", (100, 500))               // Find out more about the filters at:
+    .nxl("population_range", (100, 500))              // https://postgrest.org/en/stable/api.html#operators
     .nxr("population_range", (100, 500))
     .adj("population_range", (100, 500))
     .select("*")
     .execute()
     .await?;
 ```
 
-More examples incoming!
-
-## Limitations
-
-This library doesn't show the full extent of PostgREST, and definitely doesn't
-replace the need to learn PostgREST. Some known limitations are:
-
--   Doesn't support `not`, `and`, and `or` in filtering
--   Many inputs are unsanitized (multi-column select, insert/update body, etc.)
--   Counting (with HEAD verb)
--   Resource embedding (embedded filters, etc.)
-
-That said, if there are any features you want in, feel free to create an issue!
+Check out the [API docs](https://docs.rs/postgrest) for more info!
 
 ## Contributing
 
--   Fork the repo on GitHub
--   Clone the project to your own machine
--   Commit changes to your own branch
--   Push your work back up to your fork
--   Submit a Pull request so that we can review your changes and merge
+Contributions are welcome! There might be some features you want in, or some
+unclear documentation, or a bug—either way, feel free to create an issue, and
+we'll work it out!
+
+Boring stuff below.
 
 Unless you explicitly state otherwise, any contribution intentionally submitted
 for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
@@ -122,7 +115,7 @@ dual licensed as below, without any additional terms or conditions.
 Licensed under either of
 
 -   Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
-    http://www.apache.org/licenses/LICENSE-2.0)
--   MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
+    https://www.apache.org/licenses/LICENSE-2.0)
+-   MIT license ([LICENSE-MIT](LICENSE-MIT) or https://opensource.org/licenses/MIT)
 
 at your option.