From 70e3c902849de001dfc872bfd095274ce3c89552 Mon Sep 17 00:00:00 2001 From: Dan Kubb Date: Thu, 13 Aug 2009 21:25:11 -0700 Subject: [PATCH] Minor formatting changes to antw's excellent documentation patches [#997 state:resolved] --- lib/dm-core/query/conditions/comparison.rb | 93 +++++++++++++++++----- 1 file changed, 72 insertions(+), 21 deletions(-) diff --git a/lib/dm-core/query/conditions/comparison.rb b/lib/dm-core/query/conditions/comparison.rb index 8ac4fc7b..1389a8a2 100644 --- a/lib/dm-core/query/conditions/comparison.rb +++ b/lib/dm-core/query/conditions/comparison.rb @@ -59,7 +59,6 @@ def self.new(slug, subject, value) if klass = comparison_class(slug) klass.new(subject, value) else - # TODO: Spec me raise ArgumentError, "No Comparison class for `#{slug.inspect}' has been defined" end @@ -83,6 +82,7 @@ def self.comparison_class(slug) # Returns an array of all slugs registered with Comparison # # @return [Array] + # # @api private def self.slugs @slugs ||= @@ -97,6 +97,7 @@ class << self # Holds comparison subclasses keyed on their slug # # @return [Hash] + # # @api private def comparison_classes @comparison_classes ||= {} @@ -113,6 +114,7 @@ class AbstractComparison # The property or relationship which is being matched against # # @return [Property, Associations::Relationship] + # # @api semipublic attr_reader :subject @@ -126,6 +128,7 @@ class AbstractComparison # the repository. # # @return [Object] + # # @api semipublic attr_reader :value @@ -147,6 +150,7 @@ class AbstractComparison #++ # # @return [Object] + # # @api semipublic attr_reader :loaded_value @@ -194,7 +198,7 @@ def self.slug(slug = nil) # @see DataMapper::Property#valid? # @see DataMapper::Associations::Relationship#valid? # - # @return [TrueClass, FalseClass] + # @return [Boolean] # # @api semipublic def valid? @@ -207,7 +211,8 @@ def valid? # Returns whether the subject is a Relationship # - # @return [TrueClass, FalseClass] + # @return [Boolean] + # # @api semipublic def relationship? false @@ -215,7 +220,8 @@ def relationship? # Returns whether the subject is a Property # - # @return [TrueClass, FalseClass] + # @return [Boolean] + # # @api semipublic def property? subject.kind_of?(Property) @@ -227,6 +233,7 @@ def property? # value will have the same hash-code. # # @return [Fixnum] The computed hash-code. + # # @api semipublic def hash [ self.class, @subject, @value ].hash @@ -240,7 +247,7 @@ def hash # @param [Object] other # Another object to be compared against this one. # - # @return [TrueClass, FalseClass] + # @return [Boolean] # # @api semipublic def ==(other) @@ -261,7 +268,7 @@ def ==(other) # @param [Object] other # Another object to be compared against this one. # - # @return [TrueClass, FalseClass] + # @return [Boolean] # # @api semipublic def eql?(other) @@ -274,6 +281,7 @@ def eql?(other) # Returns a human-readable representation of this object # # @return [String] + # # @api semipublic def inspect "#<#{self.class} @subject=#{@subject.inspect} " \ @@ -287,6 +295,7 @@ def inspect # # => "my_property == value" # # @return [String] + # # @api semipublic def to_s "#{@subject} #{comparator_string} #{@value}" @@ -295,7 +304,9 @@ def to_s private # ============================================================ # Holds the actual value of the given property or relationship + # # @return [Object] + # # @api semipublic attr_reader :expected @@ -316,6 +327,7 @@ def initialize(subject, value) end # Used by Ruby when creating a copy of the comparison + # # @api private def initialize_copy(*) @value = @value.dup @@ -333,7 +345,7 @@ def initialize_copy(*) # @see AbstractComparison#== # @see AbstractComparison#eql? # - # @return [TrueClass, FalseClass] + # @return [Boolean] # # @api private def cmp?(other, operator) @@ -349,8 +361,11 @@ def cmp?(other, operator) # If the subject has no typecast method the value is returned without # any changes. # - # @param [Object] val The object to attempt to typecast. - # @return [Object] The typecasted object. + # @param [Object] val + # The object to attempt to typecast. + # + # @return [Object] + # The typecasted object. # # @see Property#typecast # @@ -368,8 +383,11 @@ def typecast_value(val) # This converts property values to the primitive as stored in the # repository. # - # @param [Object] val The object to attempt to typecast. - # @return [Object] The raw (dumped) object. + # @param [Object] val + # The object to attempt to typecast. + # + # @return [Object] + # The raw (dumped) object. # # @see Property#value # @@ -416,6 +434,7 @@ def record_value(record, subject = @subject, key_type = :source_key) # given +hash+. # # @return [Object] + # # @see AbstractComparison#record_value # # @api private @@ -436,6 +455,7 @@ def record_value_from_hash(hash, subject, key_type) # given +resource+. # # @return [Object] + # # @see AbstractComparison#record_value # # @api private @@ -451,6 +471,7 @@ def record_value_from_resource(resource, subject, key_type) # Retrieves the value of the +subject+ # # @return [Object] + # # @api semipublic def expected_value(val = @loaded_value) expected_value = record_value(val, @subject, :target_key) @@ -482,7 +503,8 @@ def comparator_string module RelationshipHandler # Returns whether this comparison subject is a Relationship # - # @return [TrueClass, FalseClass] + # @return [Boolean] + # # @api semipublic def relationship? subject.kind_of?(Associations::Relationship) @@ -491,6 +513,7 @@ def relationship? # Returns the conditions required to match the subject relationship # # @return [Hash] + # # @api semipublic def foreign_key_mapping relationship = subject.inverse @@ -512,7 +535,7 @@ class EqualToComparison < AbstractComparison # @param [Resource, Hash] record # The record containing the value to be matched # - # @return [TrueClass, FalseClass] + # @return [Boolean] # @api semipublic def matches?(record) record_value(record) == expected @@ -521,7 +544,9 @@ def matches?(record) private # @return [String] + # # @see AbstractComparison#to_s + # # @api private def comparator_string '=' @@ -541,7 +566,8 @@ class InclusionComparison < AbstractComparison # @param [Resource, Hash] record # The record containing the value to be matched # - # @return [TrueClass, FalseClass] + # @return [Boolean] + # # @api semipublic def matches?(record) record_value = record_value(record) @@ -551,7 +577,8 @@ def matches?(record) # Checks that the Comparison is valid # # @see DataMapper::Query::Conditions::AbstractComparison#valid? - # @return [TrueClass, FalseClass] + # + # @return [Boolean] # # @api semipublic def valid? @@ -578,6 +605,7 @@ def expected_value # Typecasts each value in the inclusion set # # @return [Array] + # # @see AbtractComparison#typecast_value # # @api private @@ -592,6 +620,7 @@ def typecast_value(val) # Dumps the given +val+ using subject#value # # @return [Array] + # # @see AbtractComparison#dumped_value # # @api private @@ -604,7 +633,9 @@ def dumped_value(val) end # @return [String] + # # @see AbstractComparison#to_s + # # @api private def comparator_string 'IN' @@ -621,7 +652,8 @@ class RegexpComparison < AbstractComparison # @param [Resource, Hash] record # The record containing the value to be matched # - # @return [TrueClass, FalseClass] + # @return [Boolean] + # # @api semipublic def matches?(record) record_value = record_value(record) @@ -631,6 +663,7 @@ def matches?(record) # Checks that the Comparison is valid # # @see AbstractComparison#valid? + # # @api semipublic def valid? value.kind_of?(Regexp) @@ -641,13 +674,16 @@ def valid? # Returns the value untouched # # @return [Object] + # # @api private def typecast_value(val) val end # @return [String] + # # @see AbstractComparison#to_s + # # @api private def comparator_string '=~' @@ -666,7 +702,8 @@ class LikeComparison < AbstractComparison # @param [Resource, Hash] record # The record containing the value to be matched # - # @return [TrueClass, FalseClass] + # @return [Boolean] + # # @api semipublic def matches?(record) record_value = record_value(record) @@ -681,6 +718,7 @@ def matches?(record) # records value. # # @return [Regexp] + # # @see AbtractComparison#expected_value # # @api semipublic @@ -689,7 +727,9 @@ def expected_value end # @return [String] + # # @see AbstractComparison#to_s + # # @api private def comparator_string 'LIKE' @@ -706,7 +746,8 @@ class GreaterThanComparison < AbstractComparison # @param [Resource, Hash] record # The record containing the value to be matched # - # @return [TrueClass, FalseClass] + # @return [Boolean] + # # @api semipublic def matches?(record) record_value = record_value(record) @@ -716,7 +757,9 @@ def matches?(record) private # @return [String] + # # @see AbstractComparison#to_s + # # @api private def comparator_string '>' @@ -733,7 +776,8 @@ class LessThanComparison < AbstractComparison # @param [Resource, Hash] record # The record containing the value to be matched # - # @return [TrueClass, FalseClass] + # @return [Boolean] + # # @api semipublic def matches?(record) record_value = record_value(record) @@ -743,7 +787,9 @@ def matches?(record) private # @return [String] + # # @see AbstractComparison#to_s + # # @api private def comparator_string '<' @@ -760,7 +806,8 @@ class GreaterThanOrEqualToComparison < AbstractComparison # @param [Resource, Hash] record # The record containing the value to be matched # - # @return [TrueClass, FalseClass] + # @return [Boolean] + # # @api semipublic def matches?(record) record_value = record_value(record) @@ -770,6 +817,7 @@ def matches?(record) private # @see AbstractComparison#to_s + # # @api private def comparator_string '>=' @@ -786,7 +834,8 @@ class LessThanOrEqualToComparison < AbstractComparison # @param [Resource, Hash] record # The record containing the value to be matched # - # @return [TrueClass, FalseClass] + # @return [Boolean] + # # @api semipublic def matches?(record) record_value = record_value(record) @@ -796,7 +845,9 @@ def matches?(record) private # @return [String] + # # @see AbstractComparison#to_s + # # @api private def comparator_string '<='