acfs 0.16.0 → 0.17.0

data/lib/acfs/model/initialization.rb

@@ -4,8 +4,11 @@ module Acfs::Model
   #
   module Initialization
 
-    # Initializes a new model with the given +params+.
+    # @api public
     #
+    # Initializes a new model with the given `params`.
+    #
+    # @example
     #   class User
     #     include Acfs::Model
     #     attribute :name
@@ -18,7 +21,9 @@ module Acfs::Model
     #   user.email # => "bob@dom.tld"
     #   user.age   # => 18
     #
-    def initialize(params={})
+    # @param [ Hash{ Symbol => Object } ] params Attributes to set on resource.
+    #
+    def initialize(params = {})
       params.each do |attr, value|
         self.public_send("#{attr}=", value)
       end if params

data/lib/acfs/model/loadable.rb

@@ -1,14 +1,30 @@
 module Acfs::Model
 
+  # Provides method to check for loading state of resources.
+  # A resource that is created but not yet fetched will be loaded
+  # after running {Acfs::Global#run Acfs.run}.
+  #
+  # @example
+  #   user = User.find 5
+  #   user.loaded? # => false
+  #   Acfs.run
+  #   user.loaded? # => true
+  #
   module Loadable
     extend ActiveSupport::Concern
 
+    # @api public
+    #
     # Check if model is loaded or if request is still queued.
     #
+    # @return [ Boolean ] True if resource is loaded, false otherwise.
+    #
     def loaded?
       !!@loaded
     end
 
+    # @api private
+    #
     # Mark model as loaded.
     #
     def loaded!

data/lib/acfs/model/locatable.rb

@@ -2,25 +2,46 @@ module Acfs::Model
 
   # Provide methods for generation URLs for resources.
   #
-  # Example
+  # @example
   #   class User
   #     service AccountService # With base URL `http://acc.svr`
   #   end
-  #   User.url             #=> "http://acc.svr/users"
-  #   User.url(5)          #=> "http://acc.svr/users/5"
+  #   User.url    # => "http://acc.svr/users"
+  #   User.url(5) # => "http://acc.svr/users/5"
   #
   module Locatable
     extend ActiveSupport::Concern
 
     module ClassMethods
 
-      # Return URL for this resource.
+      # Return URL for this class of resource. Given suffix will be appended.
+      #
+      # @example
+      #   User.url    # => "http://users.srv.org/users"
+      #   User.url(5) # => "http://users.srv.org/users/5"
+      #
+      # @param [ String ] suffix Suffix to append to URL.
+      # @return [ String ] Generated URL.
+      # @see Acfs::Service#url_for Delegates to Service#url_for with `suffix` option.
       #
       def url(suffix = nil)
         service.url_for(self, suffix: suffix)
       end
     end
 
+    # Return URL for this resource. Resource if will be appended
+    # as suffix if present.
+    #
+    # @example
+    #   user.new.url # => "http://users.srv.org/users"
+    #
+    #   user = User.find 5
+    #   Acfs.run
+    #   user.url # => "http://users.srv.org/users/5"
+    #
+    # @return [ String ] Generated URL.
+    # @see ClassMethods#url
+    #
     def url
       return nil if id.nil?
       self.class.service.url_for self, suffix: read_attribute(:id)

data/lib/acfs/model/operational.rb

@@ -1,5 +1,7 @@
 module Acfs::Model
 
+  # @api private
+  #
   # Provide methods for creating and processing CRUD operations and
   # handling responses. That includes error handling as well as
   # handling stubbed resources.
@@ -11,6 +13,8 @@ module Acfs::Model
     delegate :operation, to: :'self.class'
 
     module ClassMethods
+
+      # Invoke CRUD operation.
       def operation(action, opts = {}, &block)
         Acfs.runner.process ::Acfs::Operation.new self, action, opts, &block
       end

data/lib/acfs/model/persistence.rb

@@ -6,39 +6,54 @@ module Acfs
     module Persistence
       extend ActiveSupport::Concern
 
+      # @api public
+      #
       # Check if the model is persisted. A model is persisted if
       # it is saved after beeing created or when it was not changed
       # since it was loaded.
       #
-      # user = User.new name: "John"
-      # user.persisted? # => false
-      # user.save
-      # user.persisted? # => true
+      # @example Newly created resource:
+      #   user = User.new name: "John"
+      #   user.persisted? # => false
+      #   user.save
+      #   user.persisted? # => true
+      #
+      # @example Modified resource:
+      #   user2 = User.find 5
+      #   user2.persisted? # => true
+      #   user2.name = 'Amy'
+      #   user2.persisted? # => false
+      #   user2.save
+      #   user2.persisted? # => true
       #
-      # user2 = User.find 5
-      # user2.persisted? # => true
-      # user2.name = 'Amy'
-      # user2.persisted? # => false
-      # user2.save
-      # user2.persisted? # => true
+      # @return [ Boolean ] True if resource has no changes and is not newly created, false otherwise.
       #
       def persisted?
         !new? && !changed?
       end
 
+      # @api public
+      #
       # Return true if model is a new record and was not saved yet.
       #
+      # @return [ Boolean ] True if resource is newly created, false otherwise.
+      #
       def new?
         read_attribute(:id).nil?
       end
       alias :new_record? :new?
 
-      # Save the resource.
+      # @api public
+      #
+      # Saves the resource.
       #
-      # It will PATCH to the service to update the resource or send
+      # It will PUT to the service to update the resource or send
       # a POST to create a new one if the resource is new.
       #
-      # `#save` return true of operation was successful, otherwise false.
+      # Saving a resource is a synchronous operation.
+      #
+      # @return [ Boolean ] True if save operation was successful, false otherwise.
+      # @see #save! See #save! for available options.
       #
       def save(*args)
         save! *args
@@ -47,7 +62,23 @@ module Acfs
         false
       end
 
-      def save!(opts = {}) # :nodoc:
+      # @api public
+      #
+      # Saves the resource. Raises an error if something happens.
+      #
+      # Saving a resource is a synchronous operation.
+      #
+      # @param [ Hash ] opts Hash with additional options.
+      # @option opts [ Hash ] :data Data to send to remote service. Default will be resource attributes.
+      #
+      # @raise [ Acfs::InvalidResource ]
+      #   If remote services respond with 422 response. Will fill errors with data from response
+      # @raise [ Acfs::ErroneousResponse ]
+      #   If remote service respond with not successful response.
+      #
+      # @see #save
+      #
+      def save!(opts = {})
         #raise ::Acfs::InvalidResource errors: errors.to_a unless valid?
 
         opts[:data] = attributes unless opts[:data]
@@ -59,19 +90,47 @@ module Acfs
 
       module ClassMethods
 
+        # @api public
+        #
         # Create a new resource sending given data. If resource cannot be
         # created an error will be thrown.
         #
+        # Saving a resource is a synchronous operation.
+        #
+        # @param [ Hash{ Symbol, String => Object }] data Data to send in create request.
+        # @return [ self ] Newly resource object.
+        #
+        # @raise [ Acfs::InvalidResource ]
+        #   If remote services respond with 422 response. Will fill errors with data from response
+        # @raise [ Acfs::ErroneousResponse ]
+        #   If remote service respond with not successful response.
+        #
+        # @see Acfs::Model::Persistence#save! Available options. `:data` will be overridden with provided data hash.
+        # @see #create
+        #
         def create!(data, opts = {})
           new.tap do |model|
             model.save! opts.merge data: data
           end
         end
 
+        # @api public
+        #
         # Create a new resource sending given data. If resource cannot be
         # create model will be returned and error hash contains response
         # errors if available.
         #
+        # Saving a resource is a synchronous operation.
+        #
+        # @param [ Hash{ Symbol, String => Object }] data Data to send in create request.
+        # @return [ self ] Newly resource object.
+        #
+        # @raise [ Acfs::ErroneousResponse ]
+        #   If remote service respond with not successful response.
+        #
+        # @see Acfs::Model::Persistence#save! Available options. `:data` will be overridden with provided data hash.
+        # @see #create!
+        #
         def create(data, opts = {})
           model = new
           model.save! opts.merge data: data

data/lib/acfs/model/query_methods.rb

@@ -2,7 +2,7 @@ module Acfs::Model
 
   # Methods providing the query interface for finding resouces.
   #
-  # Example
+  # @example
   #   class MyUser
   #     include Acfs::Model
   #   end
@@ -18,13 +18,41 @@ module Acfs::Model
 
     module ClassMethods
 
-      # Try to load a resource by given id.
+      # @api public
       #
-      # Example
-      #   User.find(5)       # Will query `http://base.url/users/5`
-      #   User.find(1, 2, 5) # Will return collection and will query
-      #                      # `http://base.url/users/1`, `http://base.url/users/2`
-      #                      # and `http://base.url/users/5` parallel
+      # @overload find(id, opts = {})
+      #   Find a single resource by given ID.
+      #
+      #   @example
+      #     user = User.find(5) # Will query `http://base.url/users/5`
+      #
+      #   @param [ Fixnum  ] id Resource IDs to fetch from remote service.
+      #   @param [ Hash ] opts Additional options.
+      #   @option opts [ Hash ] :params Additional parameters added to request. `:id` will be overridden
+      #     with given ID.
+      #
+      #   @yield [ resource ] Callback block to be executed after resource was fetched successfully.
+      #   @yieldparam resource [ self ] Fetched resources.
+      #
+      #   @return [ self ] Resource object if only one ID was given.
+      #
+      # @overload find(*ids, opts = {})
+      #   Load collection of specified resources by given IDs.
+      #
+      #   @example
+      #     User.find(1, 2, 5) # Will return collection and will request
+      #                        # `http://base.url/users/1`, `http://base.url/users/2`
+      #                        # and `http://base.url/users/5` parallel
+      #
+      #   @param [ Fixnum, ... ] ids One or more resource IDs to fetch from remote service.
+      #   @param [ Hash ] opts Additional options.
+      #   @option opts [ Hash ] :params Additional parameters added to request. `:id` will be overridden
+      #     with individual resource ID.
+      #
+      #   @yield [ collection ] Callback block to be executed after collection was fetched successfully.
+      #   @yieldparam resource [ Collection ] Collection with fetched resources.
+      #
+      #   @return [ Collection ] Collection of requested resources if multiple IDs were given.
       #
       def find(*attrs, &block)
         opts  = attrs.extract_options!
@@ -32,8 +60,17 @@ module Acfs::Model
         attrs.size > 1 ? find_multiple(attrs, opts, &block) : find_single(attrs[0], opts, &block)
       end
 
+      # @api public
+      #
       # Try to load all resources.
       #
+      # @param [ Hash  ] params Request parameters that will be send to remote service.
+      #
+      # @yield [ collection ] Callback block to be executed when resource collection was loaded successfully.
+      # @yieldparam collection [ Collection ] Collection of fetched resources.
+      #
+      # @return [ Collection ] Collection of requested resources.
+      #
       def all(params = {}, &block)
         collection = ::Acfs::Collection.new
 

data/lib/acfs/model/service.rb

@@ -1,24 +1,36 @@
 module Acfs::Model
 
-  # Included by Acfs::Model. Allows a model to belong to a service.
+  # Included by Acfs::Model. Allows to configure the service
+  # a resource belongs to.
   #
   module Service
     extend ActiveSupport::Concern
 
     module ClassMethods
 
-      # Link to service this model belongs to. Connection settings like base URL
-      # are fetched from service. Return assigned service if no arguments are given.
+      # @api public
       #
-      # Example
-      #   class AccountService < Acfs::Client
-      #     self.base_url = 'http://acc.serv.org'
-      #   end
+      # @overload service()
+      #   Return service instance.
       #
-      #   class MyUser
-      #     service AccountService
-      #   end
-      #   MyUser.find 5 # Will fetch `http://acc.serv.org/users/5`
+      #   @return [ Service ] Service class instance.
+      #
+      # @overload service(klass, options = {})
+      #   Link to service this model belongs to. Connection settings like base URL
+      #   are fetched from service. Return assigned service if no arguments are given.
+      #
+      #   @example
+      #     class AccountService < Acfs::Client
+      #       self.base_url = 'http://acc.serv.org'
+      #     end
+      #
+      #     class MyUser
+      #       service AccountService
+      #     end
+      #     MyUser.find 5 # Will fetch `http://acc.serv.org/users/5`
+      #
+      #   @param [ Class ] klass Service class derived from {Acfs::Service}.
+      #   @param [ Object ] options Option delegated to service class initializer.
       #
       def service(klass = nil, options = {})
         return @service unless klass

data/lib/acfs/operation.rb

@@ -1,5 +1,7 @@
 module Acfs
 
+  # @api private
+  #
   # Describes a CRUD operation. Handle request creation and response
   # processing as well as error handling and stubbing.
   #

data/lib/acfs/runner.rb

@@ -2,6 +2,8 @@ require 'acfs/service/middleware'
 
 module Acfs
 
+  # @api private
+  #
   class Runner
     include Service::Middleware
     attr_reader :adapter
@@ -59,6 +61,7 @@ module Acfs
     def clear
       queue.clear
       adapter.abort
+      @running = false
     end
 
     private

data/lib/acfs/service.rb

@@ -2,21 +2,38 @@ require 'acfs/service/middleware'
 
 module Acfs
 
-  # Service object.
+  # User {Acfs::Service} to define your services. That includes
+  # an identity used to identify the service in configuration files
+  # and middlewares the service uses.
+  #
+  # Configure your service URLs in a YAML file loaded in an
+  # initializer using the identity as a key:
+  #
+  #   production:
+  #     services:
+  #       user_service_key: "http://users.service.org/base/path"
+  #
+  # @example
+  #   class UserService < Acfs::Service
+  #     identity :user_service_key
+  #
+  #     use Acfs::Middleware::MessagePackDecoder
+  #   end
   #
   class Service
     attr_accessor :options
 
     include Service::Middleware
 
+    # @api private
+    #
     def initialize(options = {})
       @options = options
     end
 
-    def options
-      @options
-    end
-
+    # @api private
+    # @return [String]
+    #
     def url_for(resource_class, options = {})
       options.reverse_merge! self.options
 
@@ -28,11 +45,27 @@ module Acfs
 
     class << self
 
+      # @api public
+      #
+      # @overload identity()
+      #   Return configured identity key or derive key from class name.
+      #
+      #   @return [Symbol] Service identity key.
+      #
+      # @overload identity(identity)
+      #   Set identity key.
+      #
+      #   @param [#to_s] identity New identity key.
+      #   @return [Symbol] New set identity key.
+      #
       def identity(identity = nil)
         @identity = identity.to_s.to_sym unless identity.nil?
         @identity ||= name.to_sym
       end
 
+      # @api private
+      # @return [String]
+      #
       def base_url
         unless (base = Acfs::Configuration.current.locate identity)
           raise ArgumentError, "#{identity} not configured. Add `locate '#{identity.to_s.underscore}', 'http://service.url/'` to your configuration."