Add docs for Attribute

lib/virtus/attribute.rb

@@ -1,5 +1,20 @@
 module Virtus
 
+  # Attribute objects handle coercion and provide interface to hook into an
+  # attribute set instance that's included into a class or object
+  #
+  # @example
+  #
+  #   # non-strict mode
+  #   attr = Virtus::Attribute.build(Integer)
+  #   attr.coerce('1')
+  #   # => 1
+  #
+  #   # strict mode
+  #   attr = Virtus::Attribute.build(Integer, :strict => true)
+  #   attr.coerce('not really coercible')
+  #   # => Virtus::CoercionError: Failed to coerce "fsafa" into Integer
+  #
   class Attribute
     extend DescendantsTracker, Options, TypeLookup
 
@@ -24,22 +39,28 @@ def self.coerce(value = Undefined)
       self
     end
 
-    attr_reader :type, :primitive, :options, :default_value, :coercer
+    # Return type of this attribute
+    #
+    # @return [Axiom::Types::Type]
+    #
+    # @api public
+    attr_reader :type
+
+    # @api private
+    attr_reader :primitive, :options, :default_value, :coercer
 
     # Builds an attribute instance
     #
-    # @param [Symbol] name
-    #   the name of an attribute
-    #
-    # @param [Class] type
-    #   optional type class of an attribute
+    # @param [Class,Array,Hash,String,Symbol] type
+    #   this can be an explicit class or an object from which virtus can infer
+    #   the type
     #
     # @param [#to_hash] options
     #   optional extra options hash
     #
     # @return [Attribute]
     #
-    # @api private
+    # @api public
     def self.build(type, options = {})
       Builder.call(type, options)
     end
@@ -62,16 +83,6 @@ def self.merge_options!(*)
       # noop
     end
 
-    # Initializes an attribute instance
-    #
-    # @param [#to_sym] name
-    #   the name of an attribute
-    #
-    # @param [#to_hash] options
-    #   hash of extra options which overrides defaults set on an attribute class
-    #
-    # @return [undefined]
-    #
     # @api private
     def initialize(type, options)
       @type          = type
@@ -81,45 +92,122 @@ def initialize(type, options)
       @coercer       = options.fetch(:coercer)
     end
 
+    # Coerce the input into the expected type
+    #
+    # @example
+    #
+    #   attr = Virtus::Attribute.build(String)
+    #   attr.coerce(:one) # => 'one'
+    #
+    # @param [Object] input
+    #
     # @api public
-    def coerce(value)
-      coercer.call(value)
+    def coerce(input)
+      coercer.call(input)
     end
 
+    # Return a new attribute with the new name
+    #
+    # @param [Symbol] name
+    #
+    # @return [Attribute]
+    #
     # @api public
     def rename(name)
       self.class.build(type, options.merge(:name => name))
     end
 
+    # Return if the given value was coerced
+    #
+    # @param [Object] value
+    #
+    # @return [Boolean]
+    #
     # @api public
     def value_coerced?(value)
       coercer.success?(primitive, value)
     end
 
     # Return if the attribute is coercible
     #
+    # @example
+    #
+    #   attr = Virtus::Attribute.build(String, :coerce => true)
+    #   attr.coercible? # => true
+    #
+    #   attr = Virtus::Attribute.build(String, :coerce => false)
+    #   attr.coercible? # => false
+    #
     # @return [Boolean]
     #
     # @api public
     def coercible?
       kind_of?(Coercible)
     end
 
+    # Return if the attribute has lazy default value evaluation
+    #
+    # @example
+    #
+    #   attr = Virtus::Attribute.build(String, :lazy => true)
+    #   attr.lazy? # => true
+    #
+    #   attr = Virtus::Attribute.build(String, :lazy => false)
+    #   attr.lazy? # => false
+    #
+    # @return [Boolean]
+    #
     # @api public
     def lazy?
       kind_of?(LazyDefault)
     end
 
+    # Return if the attribute is in the strict coercion mode
+    #
+    # @example
+    #
+    #   attr = Virtus::Attribute.build(String, :strict => true)
+    #   attr.strict? # => true
+    #
+    #   attr = Virtus::Attribute.build(String, :strict => false)
+    #   attr.strict? # => false
+    #
+    # @return [Boolean]
+    #
     # @api public
     def strict?
       kind_of?(Strict)
     end
 
+    # Return if the attribute is accepts nil values as valid coercion output
+    #
+    # @example
+    #
+    #   attr = Virtus::Attribute.build(String, :required => true)
+    #   attr.required? # => true
+    #
+    #   attr = Virtus::Attribute.build(String, :required => false)
+    #   attr.required? # => false
+    #
+    # @return [Boolean]
+    #
     # @api public
     def required?
       options[:required]
     end
 
+    # Return if the attribute was already finalized
+    #
+    # @example
+    #
+    #   attr = Virtus::Attribute.build(String, :finalize => true)
+    #   attr.finalized? # => true
+    #
+    #   attr = Virtus::Attribute.build(String, :finalize => false)
+    #   attr.finalized? # => false
+    #
+    # @return [Boolean]
+    #
     # @api public
     def finalized?
       frozen?