From 0b0ac14b1997372524f08eba96ae21e20a47bc83 Mon Sep 17 00:00:00 2001 From: Chris Anderson Date: Thu, 2 Oct 2008 11:32:11 -0700 Subject: [PATCH] clean up comments way more --- lib/couchrest/core/model.rb | 104 +++++++++++++++++++++++++----------- 1 file changed, 72 insertions(+), 32 deletions(-) diff --git a/lib/couchrest/core/model.rb b/lib/couchrest/core/model.rb index e6ec6b4..f9151e4 100644 --- a/lib/couchrest/core/model.rb +++ b/lib/couchrest/core/model.rb @@ -1,13 +1,18 @@ # = CouchRest::Model - ORM, the CouchDB way module CouchRest # = CouchRest::Model - ORM, the CouchDB way - # - # CouchRest::Model provides an ORM-like interface for CouchDB documents. It avoids all usage of method_missing, and tries to strike a balance between usability and magic. See CouchRest::Model#view_by for documentation about the view-generation system. - # + # + # CouchRest::Model provides an ORM-like interface for CouchDB documents. It + # avoids all usage of method_missing, and tries to strike a balance + # between usability and magic. See CouchRest::Model#view_by for + # documentation about the view-generation system. + # # ==== Example - # - # This is an example class using CouchRest::Model. It is taken from the spec/couchrest/core/model_spec.rb file, which may be even more up to date than this example. - # + # + # This is an example class using CouchRest::Model. It is taken from the + # spec/couchrest/core/model_spec.rb file, which may be even more up to date + # than this example. + # # class Article < CouchRest::Model # use_database CouchRest.database!('http://localhost:5984/couchrest-model-test') # unique_id :slug @@ -54,7 +59,8 @@ module CouchRest end class << self - # this is the CouchRest::Database that model classes will use unless they override it with use_database + # this is the CouchRest::Database that model classes will use unless + # they override it with use_database attr_accessor :default_database # override the CouchRest::Model-wide default_database @@ -73,13 +79,15 @@ module CouchRest new(doc) end - # Defines methods for reading and writing from fields in the document. Uses key_writer and key_reader internally. + # Defines methods for reading and writing from fields in the document. + # Uses key_writer and key_reader internally. def key_accessor *keys key_writer *keys key_reader *keys end - # For each argument key, define a method key= that sets the corresponding field on the CouchDB document. + # For each argument key, define a method key= that sets the + # corresponding field on the CouchDB document. def key_writer *keys keys.each do |method| key = method.to_s @@ -89,7 +97,8 @@ module CouchRest end end - # For each argument key, define a method key that reads the corresponding field on the CouchDB document. + # For each argument key, define a method key that reads the + # corresponding field on the CouchDB document. def key_reader *keys keys.each do |method| key = method.to_s @@ -99,7 +108,9 @@ module CouchRest end end - # Automatically set updated_at and created_at fields on the document whenever saving occurs. CouchRest uses a pretty decent time format by default. See Time#to_json + # Automatically set updated_at and created_at fields + # on the document whenever saving occurs. CouchRest uses a pretty + # decent time format by default. See Time#to_json def timestamps! before(:create) do self['updated_at'] = self['created_at'] = Time.now @@ -109,26 +120,33 @@ module CouchRest end end - # Name a method that will be called before the document is first saved, which returns a string to be used for the document's _id. Because CouchDB enforces a constraint that each id must be unique, this can be used to enforce eg: uniq usernames. Note that this id must be globally unique across all document types which share a database, so if you'd like to scope uniqueness to this class, you should use the class name as part of the unique id. + # Name a method that will be called before the document is first saved, + # which returns a string to be used for the document's _id. + # Because CouchDB enforces a constraint that each id must be unique, + # this can be used to enforce eg: uniq usernames. Note that this id + # must be globally unique across all document types which share a + # database, so if you'd like to scope uniqueness to this class, you + # should use the class name as part of the unique id. def unique_id method define_method :set_unique_id do self['_id'] ||= self.send(method) end end - # Define a CouchDB view. The name of the view will be the concatenation of by and the keys joined by _and_ - # + # Define a CouchDB view. The name of the view will be the concatenation + # of by and the keys joined by _and_ + # # ==== Example views: - # + # # class Post # # view with default options # # query with Post.by_date # view_by :date, :descending => true - # + # # # view with compound sort-keys # # query with Post.by_user_id_and_date # view_by :user_id, :date - # + # # # view with custom map/reduce functions # # query with Post.by_tags :reduce => true # view_by :tags, @@ -145,24 +163,38 @@ module CouchRest # return sum(values); # }" # end - # - # view_by :date will create a view defined by this Javascript function: - # + # + # view_by :date will create a view defined by this Javascript + # function: + # # function(doc) { # if (doc.type == 'Post' && doc.date) { # emit(doc.date, null); # } # } - # - # It can be queried by calling Post.by_date which accepts all valid options for CouchRest::Database#view. In addition, calling with the :raw => true option will return the view rows themselves. By default Post.by_date will return the documents included in the generated view. - # - # CouchRest::Database#view options can be applied at view definition time as defaults, and they will be curried and used at view query time. Or they can be overridden at query time. - # - # Custom views can be queried with :reduce => true to return reduce results. The default for custom views is to query with :reduce => false. - # - # Views are generated (on a per-model basis) lazily on first-access. This means that if you are deploying changes to a view, the views for that model won't be available until generation is complete. This can take some time with large databases. Strategies are in the works. - # - # To understand the capabilities of this view system more compeletly, it is recommended that you read the RSpec file at spec/core/model.rb. + # + # It can be queried by calling Post.by_date which accepts all + # valid options for CouchRest::Database#view. In addition, calling with + # the :raw => true option will return the view rows + # themselves. By default Post.by_date will return the + # documents included in the generated view. + # + # CouchRest::Database#view options can be applied at view definition + # time as defaults, and they will be curried and used at view query + # time. Or they can be overridden at query time. + # + # Custom views can be queried with :reduce => true to return + # reduce results. The default for custom views is to query with + # :reduce => false. + # + # Views are generated (on a per-model basis) lazily on first-access. + # This means that if you are deploying changes to a view, the views for + # that model won't be available until generation is complete. This can + # take some time with large databases. Strategies are in the works. + # + # To understand the capabilities of this view system more compeletly, + # it is recommended that you read the RSpec file at + # spec/core/model.rb. def view_by *keys opts = keys.pop if keys.last.is_a?(Hash) opts ||= {} @@ -280,12 +312,14 @@ module CouchRest self['_rev'] end - # returns true if the self has never been saved + # returns true if the document has never been saved def new_record? !rev end - # save the doc to the db using create or update + # Saves the document to the db using create or update. Also runs the :save + # callbacks. Sets the _id and _rev fields based on + # CouchDB's response. def save if new_record? create @@ -294,6 +328,9 @@ module CouchRest end end + # Deletes the document from the database. Runs the :delete callbacks. + # Removes the _id and _rev fields, preparing the + # document to be saved to a new _id. def destroy result = database.delete self if result['ok'] @@ -305,11 +342,14 @@ module CouchRest protected + # Saves a document for the first time, after running the before(:create) + # callbacks, and applying the unique_id. def create set_unique_id if respond_to?(:set_unique_id) # hack save_doc end + # Saves the document and runs the :update callbacks. def update save_doc end