Permalink
Browse files

Update docs for yardoc

  • Loading branch information...
1 parent 85c1fd5 commit 60d916b654fd308abaa28036a0bd6897f21c6444 Sjoerd Andringa committed Aug 4, 2011
View
@@ -1,4 +1,5 @@
*.log
/doc
/rdoc
-/pkg
+/pkg
+/.yardoc
View
@@ -0,0 +1 @@
+--exclude lib/generators --no-private --protected lib/**/*.rb - README.rdoc
View
@@ -2,39 +2,40 @@ GEM
remote: http://rubygems.org/
specs:
abstract (1.0.0)
- actionmailer (3.0.9)
- actionpack (= 3.0.9)
- mail (~> 2.2.19)
- actionpack (3.0.9)
- activemodel (= 3.0.9)
- activesupport (= 3.0.9)
+ actionmailer (3.0.0)
+ actionpack (= 3.0.0)
+ mail (~> 2.2.5)
+ actionpack (3.0.0)
+ activemodel (= 3.0.0)
+ activesupport (= 3.0.0)
builder (~> 2.1.2)
erubis (~> 2.6.6)
- i18n (~> 0.5.0)
+ i18n (~> 0.4.1)
rack (~> 1.2.1)
- rack-mount (~> 0.6.14)
- rack-test (~> 0.5.7)
+ rack-mount (~> 0.6.12)
+ rack-test (~> 0.5.4)
tzinfo (~> 0.3.23)
- activemodel (3.0.9)
- activesupport (= 3.0.9)
+ activemodel (3.0.0)
+ activesupport (= 3.0.0)
builder (~> 2.1.2)
- i18n (~> 0.5.0)
- activerecord (3.0.9)
- activemodel (= 3.0.9)
- activesupport (= 3.0.9)
- arel (~> 2.0.10)
+ i18n (~> 0.4.1)
+ activerecord (3.0.0)
+ activemodel (= 3.0.0)
+ activesupport (= 3.0.0)
+ arel (~> 1.0.0)
tzinfo (~> 0.3.23)
- activeresource (3.0.9)
- activemodel (= 3.0.9)
- activesupport (= 3.0.9)
- activesupport (3.0.9)
- arel (2.0.10)
+ activeresource (3.0.0)
+ activemodel (= 3.0.0)
+ activesupport (= 3.0.0)
+ activesupport (3.0.0)
+ arel (1.0.1)
+ activesupport (~> 3.0.0)
builder (2.1.2)
diff-lcs (1.1.2)
erubis (2.6.6)
abstract (>= 1.0.0)
git (1.2.5)
- i18n (0.5.0)
+ i18n (0.4.2)
jeweler (1.6.4)
bundler (~> 1.0)
git (>= 1.2.5)
@@ -51,22 +52,20 @@ GEM
rack (>= 1.0.0)
rack-test (0.5.7)
rack (>= 1.0)
- rails (3.0.9)
- actionmailer (= 3.0.9)
- actionpack (= 3.0.9)
- activerecord (= 3.0.9)
- activeresource (= 3.0.9)
- activesupport (= 3.0.9)
- bundler (~> 1.0)
- railties (= 3.0.9)
- railties (3.0.9)
- actionpack (= 3.0.9)
- activesupport (= 3.0.9)
- rake (>= 0.8.7)
- rdoc (~> 3.4)
- thor (~> 0.14.4)
+ rails (3.0.0)
+ actionmailer (= 3.0.0)
+ actionpack (= 3.0.0)
+ activerecord (= 3.0.0)
+ activeresource (= 3.0.0)
+ activesupport (= 3.0.0)
+ bundler (~> 1.0.0)
+ railties (= 3.0.0)
+ railties (3.0.0)
+ actionpack (= 3.0.0)
+ activesupport (= 3.0.0)
+ rake (>= 0.8.4)
+ thor (~> 0.14.0)
rake (0.9.2)
- rdoc (3.9.1)
rspec (2.6.0)
rspec-core (~> 2.6.0)
rspec-expectations (~> 2.6.0)
@@ -88,7 +87,7 @@ PLATFORMS
DEPENDENCIES
jeweler (>= 1.6.4)
- rails (>= 3.0.9)
+ rails (= 3.0.0)
rspec (>= 2.6.0)
shoulda-matchers (>= 1.0.0.beta3)
sqlite3 (>= 1.3.4)
View
@@ -1,12 +1,11 @@
= HasRemote
-Binds your local ActiveRecord objects to a remote ActiveResource object,
+Binds your local <tt>ActiveRecord</tt> objects to a remote <tt>ActiveResource</tt> object,
which enables you to look for certain attributes remotely using a RESTful webservice.
=== Installation
==== Rails 3
-_(Work in progress, will be available from version 0.2.0, which hasn't been released yet)_
Add the following to your <tt>Gemfile</tt>:
@@ -121,7 +120,7 @@ Synchronize all records of one specific model:
The latter automatically requests all remote resources that have been changed (including new and deleted records) since the last successful synchronization for this particular model.
You may need to override the <tt>updated_remotes</tt> class method in your model to match your host's REST API.
-See <tt>HasRemote::Synchronizable</tt> for more information.
+See {HasRemote::Synchronizable} for more information.
==== Rake hr:sync
@@ -133,12 +132,12 @@ certain models by using the <tt>MODELS</tt> variable:
rake hr:sync MODELS=Contact,Company
-To specify additional parameters to send with the request that fetches updated resources use the PARAMS variable:
+To specify additional parameters to send with the request that fetches updated resources use the <tt>PARAMS</tt> variable:
rake hr:sync PARAMS="since=01-01-2010&limit=25"
-(If you've overridden the <tt>updated_remotes</tt> class method on one of your synchronizable models, then note that these parameters are
-passed in as a hash to <tt>updated_remotes</tt> internally.)
+(If you've overridden the {HasRemote::Synchronizable#updated_remotes #updated_remotes} class method on one of your synchronizable models, then note that these parameters are
+passed in as a hash to {HasRemote::Synchronizable#updated_remotes #updated_remotes} internally.)
=== Testing
View
@@ -2,11 +2,11 @@
require 'has_remote/synchronization'
require 'has_remote/railtie'
-# The main module for the has_remote plugin. Please see README for more information.
+# The main module for the has_remote plugin. Please see {file:README.rdoc README} for more information.
#
module HasRemote
- def self.included(base) #:nodoc:
+ def self.included(base)
base.extend ClassMethods
end
@@ -22,28 +22,18 @@ def self.models
end
# Updates cached attributes, destroys deleted records and adds new records of all models that have a remote.
- # Also see HasRemote::Synchronizable.
+ # Also see {HasRemote::Synchronizable}.
#
def self.synchronize!
models.each(&:synchronize!)
end
module ClassMethods
- # Gives your local ActiveRecord model a remote proxy (ActiveResource::Base),
- # which enables you to look for certain attributes remotely.
+ # Binds your <tt>ActiveRecord</tt> objects to a remote <tt>ActiveResource</tt> resource,
+ # and enables you to look for certain attributes remotely.
#
- # ==== Options
- #
- # [:foreign_key] The name of the column used to store the id of the remote resource. Defaults to :remote_id.
- # [:remote_primary_key] The name of the remote resource's primary key. Defaults to :id.
- # [:site, :user, :password, ...] Basically all ActiveResource configuration settings are available,
- # see http://api.rubyonrails.org/classes/ActiveResource/Base.html
- # [:through] Optional custom ActiveResource class name to use for the proxy. If not set, a default class called
- # "<ModelName>::Remote" will be created dynamically. *Note* that any ActiveResource
- # configuration options will still be applied to this class.
- #
- # ==== Usage
+ # ==== Usage:
#
# class User < ActiveRecord::Base
# has_remote :site => 'http://people.local'
@@ -57,7 +47,7 @@ module ClassMethods
# User.find(1).remote.username
# # => "User name from remote server"
#
- # has_remote also takes a block which is passed in a HasRemote::Config object which can be used to specify
+ # has_remote also takes a block which is passed in a {Config} object which can be used to specify
# remote attributes:
#
# class User < ActiveRecord::Base
@@ -71,6 +61,14 @@ module ClassMethods
# User.find(1).username
# # => "User name from remote server"
#
+ # @option options [Symbol, String] :foreign_key (:remote_id) The name of the column used to store the id of the remote resource..
+ # @option options [Symbol, String] :remote_primary_key (:id) The name of the remote resource's primary key.
+ # @option options [String] :through Optional custom <tt>ActiveResource</tt> class name to use for the proxy. If not set, a default class called
+ # <tt>Remote</tt> will be created dynamically, namespaced inside the current model. *Note* that any <tt>ActiveResource</tt>
+ # configuration options will still be applied to this class.
+ # @option options Other All other options you pass in will be used to configure the <tt>ActiveResource</tt> model, you can use any setting for {http://api.rubyonrails.org/classes/ActiveResource/Base.html ActiveResource::Base}, such as <tt>:site</tt>, <tt>:user</tt> and <tt>:password</tt>.
+ # @yieldparam [Config] remote Configure attributes to be delegated or a custom finder.
+ #
def has_remote(options, &block)
unless options[:through] || self.const_defined?("Remote")
self.const_set("Remote", Class.new(ActiveResource::Base))
@@ -123,12 +121,10 @@ def remote_attribute_aliases # :nodoc:
module InstanceMethods
- # Returns the remote proxy for this record as an <tt>ActiveResource::Base</tt> object. Returns nil
- # if foreign key is nil.
- #
- # *Arguments*
+ # Returns the remote proxy for this record as an <tt>ActiveResource::Base</tt> object. Returns <tt>nil</tt>
+ # if foreign key is <tt>nil</tt>.
#
- # - <tt>force_reload</tt>: Forces a reload from the remote server if set to true. Defaults to false.
+ # @param [Boolean] force_reload Forces a reload from the remote server if set to <tt>true</tt>.
#
def remote(force_reload = false)
if force_reload || @remote.nil?
@@ -140,6 +136,8 @@ def remote(force_reload = false)
# Checks whether a remote proxy exists.
#
+ # @return [Boolean]
+ #
def has_remote?
# NOTE ARes#exists? is broken:
# https://rails.lighthouseapp.com/projects/8994/tickets/1223-activeresource-head-request-sends-headers-with-a-nil-key
@@ -149,6 +147,8 @@ def has_remote?
# Synchronizes all locally cached remote attributes to this object and saves the object.
#
+ # @raise [ActiveRecord::RecordInvalid]
+ #
def update_cached_attributes!
update_cached_attributes
save!
@@ -157,7 +157,7 @@ def update_cached_attributes!
# Synchronizes all locally cached remote attributes to this object, but does not save the object.
#
# Note that when the remote does no longer exist, all remote attributes will be
- # set to nil.
+ # set to <tt>nil</tt>.
#
def update_cached_attributes
unless self.skip_update_cache || self.class.cached_attributes.empty?
@@ -171,20 +171,19 @@ def update_cached_attributes
end
+ # The block argument for {HasRemote::ClassMethods#has_remote} is an instance of this class.
+ # It can be used to configure HasRemote's behaviour for a model.
+ #
class Config
+
+ # @private
def initialize(base) #:nodoc:
@base = base
end
# Defines a remote attribute. Adds a getter method on instances, which delegates to the remote object.
#
- # *Options*
- #
- # [:local_cache] If set to true the attribute will also be saved locally. See README for more information
- # about caching and synchronization.
- # [:as] Optionally map remote attribute to this name.
- #
- # *Example*
+ # ==== Example:
#
# class User < ActiveRecord::Base
# has_remote :site => '...' do |remote|
@@ -193,6 +192,11 @@ def initialize(base) #:nodoc:
# end
# end
#
+ # @param [String, Symbol] attr_name The name of the attribute you want to delegate to the remote.
+ # @option options [Boolean] :local_cache (false) If set to <tt>true</tt> the attribute will also be saved locally. See {file:README.rdoc README} for more information
+ # about caching and synchronization.
+ # @option options [Symbol, String] :as Optionally map the remote attribute to this name.
+ #
def attribute(attr_name, options = {})
method_name = options[:as] || attr_name
@@ -218,12 +222,12 @@ def #{method_name}=(arg)
end
# Lets you specify custom finder logic to find the record's remote object.
- # It takes a block which is passed in the id of the remote object.
- #
- # (By default <tt>Model.remote_class.find(id)</tt> would be called.)
+ # It takes a block which is passed in the ID of the remote object.
#
- # *Example*
+ # By default the following finder is used:
+ # MyModel.remote_class.find(id)
#
+ # ==== Example:
# class User < ActiveRecord::Base
# has_remote :site => "..." do |remote|
# remote.finder do |id|
@@ -1,7 +1,8 @@
require 'rails'
module HasRemote
- class Railtie < Rails::Railtie
+ # @private
+ class Railtie < Rails::Railtie #:nodoc:
initializer 'has_remote.load' do
ActiveSupport.on_load(:active_record) do
HasRemote::Railtie.load!
Oops, something went wrong.

0 comments on commit 60d916b

Please sign in to comment.