From 054e0ef7b7bd4a164c150b08c97b5c1c21be78f9 Mon Sep 17 00:00:00 2001
From: =?utf8?q?Johan=20S=C3=B8rensen?= <johan@johansorensen.com>
Date: Sun, 9 Sep 2007 20:53:41 +0200
Subject: [PATCH] TODO and some rdocs

---
 README.txt                      | 32 +++++++++++++++++++++++++++++++-
 TODO                            |  6 ++++++
 doc/.gitignore                  |  2 --
 lib/couch_object/database.rb    |  6 ++++++
 lib/couch_object/persistable.rb |  7 ++++++-
 lib/couch_object/response.rb    |  1 +
 6 files changed, 50 insertions(+), 4 deletions(-)
 rewrite README.txt (100%)
 create mode 100644 TODO
 delete mode 100644 doc/.gitignore

diff --git a/README.txt b/README.txt
dissimilarity index 100%
index 100b938..011f1ce 100644
--- a/README.txt
+++ b/README.txt
@@ -1 +1,31 @@
-README
\ No newline at end of file
+CouchObject
+===========
+
+CouchObject is a set of classes to help you talk to CouchDb (http://couchdbwiki.com/) with Ruby.
+
+    class Bike
+      include CouchObject::Persistable
+
+      def initialize(wheels)
+        @wheels = wheels
+      end
+      attr_accessor :wheels
+
+      def to_couch
+        {:wheels => @wheels}
+      end
+
+      def self.from_couch(attributes)
+        new(attributes["wheels"])
+      end
+    end
+
+By including the CouchObject::Persistable and defining two methods on our class we specify how we should serialize and deserialize our object to and from a CouchDb:
+
+    >> bike_4wd = Bike.new(4)
+    => #<Bike:0x6a0a68 @wheels=4>
+    >> bike_4wd.save("couchobject")
+    => {"_rev"=>1745167971, "_id"=>"6FA2AFB623A93E0E77DEAAF59BB02565", "ok"=>true}
+    >> bike = Bike.get_by_id("couchobject", bike_4wd.id)
+    => #<Bike:0x64846c @wheels=4>
+    
diff --git a/TODO b/TODO
new file mode 100644
index 0000000..601b485
--- /dev/null
+++ b/TODO
@@ -0,0 +1,6 @@
+- flat namespace for object attributes? (instead of the "attributes" key)
+- Query/View API
+- better handling of document id, including setting a custom ones
+
+- CouchObject::Model for more domain specific/clearer way to model Couch docs in ruby
+- 
\ No newline at end of file
diff --git a/doc/.gitignore b/doc/.gitignore
deleted file mode 100644
index b2c1a96..0000000
--- a/doc/.gitignore
+++ /dev/null
@@ -1,2 +0,0 @@
-coverage/*
-rdoc/*
diff --git a/lib/couch_object/database.rb b/lib/couch_object/database.rb
index 4299dda..518c464 100644
--- a/lib/couch_object/database.rb
+++ b/lib/couch_object/database.rb
@@ -1,21 +1,27 @@
 module CouchObject
   class Database
+    # Create a new database at +uri+ with the name if +dbname+
     def self.create!(uri, dbname)
       server = Server.new(uri)
       Response.new(server.put("/#{dbname}", "")).parse
     end
     
+    # Delete the database at +uri+ with the name if +dbname+
     def self.delete!(uri, dbname)
       server = Server.new(uri)
       Response.new(server.delete("/#{dbname}")).parse
     end
     
+    # All databases at +uri+
     def self.all_databases(uri)
+      # FIXME: Move to Server ?
       server = Server.new(uri)
       resp = server.get("/_all_dbs")
       Response.new(resp).parse
     end
     
+    # Open a connection to the database at +uri+, where +uri+ is a full uri
+    # like: http://localhost:8888/foo
     def self.open(uri)
       uri = URI.parse(uri)
       server_uri = "#{uri.scheme}://#{uri.host}:#{uri.port}"
diff --git a/lib/couch_object/persistable.rb b/lib/couch_object/persistable.rb
index 80bc383..080e3bd 100644
--- a/lib/couch_object/persistable.rb
+++ b/lib/couch_object/persistable.rb
@@ -5,6 +5,7 @@ module CouchObject
     end
     
     module ClassMethods
+      # Get a document from +db_uri+ with +id+ as the document id
       def get_by_id(db_uri, id)
         raise NoFromCouchMethodError unless respond_to?(:from_couch)
         db = CouchObject::Database.open(db_uri)
@@ -13,6 +14,7 @@ module CouchObject
       end
     end
     
+    # Save the object to +db_uri+
     def save(db_uri)
       db = CouchObject::Database.open(db_uri)
       response = Response.new(db.post("", self.to_json)).parse
@@ -21,15 +23,18 @@ module CouchObject
       end
       response
     end
-
+    
+    # Is this a new unsaved object?
     def new?
       id.nil?
     end
 
+    # the Couch document id of this object
     def id
       @id
     end
 
+    # serializes this object, based on its #to_couch method, into JSON
     def to_json
       raise NoToCouchMethodError unless respond_to?(:to_couch)
       {"class" => self.class, "attributes" => self.to_couch}.to_json
diff --git a/lib/couch_object/response.rb b/lib/couch_object/response.rb
index 7ca9be6..1f73728 100644
--- a/lib/couch_object/response.rb
+++ b/lib/couch_object/response.rb
@@ -13,6 +13,7 @@ module CouchObject
     end
     
     def success?
+      # FIXME: make better
       (200...400).include?(code.to_i)
     end
     
-- 
2.11.4.GIT