Made Resource::ClassMethods#find_by_sql slightly more practically useful

by allowing the user to define what properties the query returns.

 * Added :property as an option to the call signature.

lib/data_mapper/adapters/data_objects_adapter.rb

@@ -22,13 +22,19 @@ module ClassMethods
       # <DataMapper::Query>:: A prepared Query to execute.
       # <Hash>:: An options hash.
       #
+      # A String, Array or Query is required.
+      #
       # ==== Options (the options hash)
-      # :repository<Symbol>:: The name of the repository to execute the query in.
-      # :reload<Boolean>:: Whether to reload any instances found that allready exist in the identity map.
+      # :repository<Symbol>:: The name of the repository to execute the query in. Defaults to self.default_repository_name.
+      # :reload<Boolean>:: Whether to reload any instances found that allready exist in the identity map. Defaults to false.
+      # :properties<Array>:: The Properties of the instance that the query loads. Must contain DataMapper::Properties. Defaults to self.properties.
       #
       # ==== Returns
       # LoadedSet:: The instance matched by the query.
       #
+      # ==== Example
+      # MyClass.find_by_sql(["SELECT id FROM my_classes WHERE county = ?", selected_county], :properties => MyClass.property[:id], :repository => :county_repo)
+      #
       # -
       # @public
       def find_by_sql(*args)
@@ -48,6 +54,7 @@ def find_by_sql(*args)
             query = arg
           elsif arg.is_a?(Hash)
             repository_name = arg.delete(:repository) if arg.include?(:repository)
+            properties = Array(arg.delete(:properties)) if arg.include?(:properties)
             do_reload = arg.delete(:reload) if arg.include?(:reload)
             raise "unknown options to #find_by_sql: #{arg.inspect}" unless arg.empty?
           end