Stubbed out @api and other docs for several classes

lib/dm-core.rb

@@ -42,6 +42,8 @@
 require dir / 'associations' / 'one_to_one'
 require dir / 'associations' / 'many_to_one'
 require dir / 'associations' / 'many_to_many'
+require dir / 'conditions' / 'boolean_operator'
+require dir / 'conditions' / 'comparisons'
 require dir / 'identity_map'
 require dir / 'migrations'                      # TODO: move to dm-more
 require dir / 'model' / 'hook'
@@ -53,8 +55,7 @@
 require dir / 'query' / 'direction'
 require dir / 'query' / 'operator'
 require dir / 'query' / 'path'
-require dir / 'conditions' / 'boolean_operator'
-require dir / 'conditions' / 'comparisons'
+require dir / 'query' / 'sort'
 require dir / 'repository'
 require dir / 'resource'
 require dir / 'support' / 'logger'
@@ -132,7 +133,7 @@ class IncompleteModelError < StandardError; end
 
   class PluginNotFoundError < StandardError; end
 
-  # TODO: document this
+  # TODO: document
   # @api private
   def self.root
     @root ||= Pathname(__FILE__).dirname.parent.expand_path.freeze

lib/dm-core/adapters.rb

@@ -3,6 +3,8 @@ module Adapters
     extend Chainable
 
     extendable do
+      # TODO: document
+      # @api private
       def const_added(const_name)
       end
     end

lib/dm-core/adapters/abstract_adapter.rb

@@ -95,6 +95,8 @@ def delete(collection)
 
       protected
 
+      # TODO: document
+      # @api semipublic
       def initialize_identity_field(resource, next_id)
         if identity_field = resource.model.identity_field(name)
           identity_field.set!(resource, next_id)
@@ -104,6 +106,8 @@ def initialize_identity_field(resource, next_id)
         end
       end
 
+      # TODO: document
+      # @api semipublic
       def attributes_as_fields(attributes)
         attributes.map { |p, v| [ p.field, v ] }.to_hash
       end

lib/dm-core/adapters/data_objects_adapter.rb

@@ -152,13 +152,17 @@ def delete(collection)
       end
 
       # Database-specific method
+      # TODO: document
+      # @api public
       def execute(statement, *bind_values)
         with_connection do |connection|
           command = connection.create_command(statement)
           command.execute_non_query(*bind_values)
         end
       end
 
+      # TODO: document
+      # @api public
       def query(statement, *bind_values)
         with_connection do |connection|
           begin
@@ -188,6 +192,8 @@ def query(statement, *bind_values)
 
       protected
 
+      # TODO: document
+      # @api private
       def normalized_uri
         @normalized_uri ||=
           begin
@@ -209,6 +215,7 @@ def normalized_uri
 
       chainable do
         protected
+
         # Instantiates new connection object
         #
         # @api semipublic
@@ -228,6 +235,8 @@ def close_connection(connection)
 
       private
 
+      # TODO: document
+      # @api public
       def initialize(name, uri_or_options)
         super
 
@@ -237,6 +246,8 @@ def initialize(name, uri_or_options)
         end
       end
 
+      # TODO: document
+      # @api private
       def with_connection
         begin
           connection = create_connection
@@ -253,7 +264,7 @@ def with_connection
       # Adapter below.
       module SQL #:nodoc:
 
-        # TODO: document this
+        # TODO: document
         # @api semipublic
         def property_to_column_name(property, qualify)
           if qualify
@@ -268,19 +279,25 @@ def property_to_column_name(property, qualify)
 
         # Adapters requiring a RETURNING syntax for INSERT statements
         # should overwrite this to return true.
+        #
+        # @api private
         def supports_returning?
           false
         end
 
         # Adapters that do not support the DEFAULT VALUES syntax for
         # INSERT statements should overwrite this to return false.
+        #
+        # @api private
         def supports_default_values?
           true
         end
 
         # Constructs SELECT statement for given query,
         #
         # @return [String] SELECT statement as a string
+        #
+        # @api private
         def select_statement(query)
           model      = query.model
           fields     = query.fields
@@ -329,6 +346,8 @@ def select_statement(query)
         # Constructs INSERT statement for given query,
         #
         # @return [String] INSERT statement as a string
+        #
+        # @api private
         def insert_statement(model, properties, identity_field)
           statement = "INSERT INTO #{quote_name(model.storage_name(name))} "
 
@@ -352,6 +371,8 @@ def insert_statement(model, properties, identity_field)
         # Constructs UPDATE statement for given query,
         #
         # @return [String] UPDATE statement as a string
+        #
+        # @api private
         def update_statement(properties, query)
           conditions_statement, bind_values = conditions_statement(query.conditions)
 
@@ -365,6 +386,8 @@ def update_statement(properties, query)
         # Constructs DELETE statement for given query,
         #
         # @return [String] DELETE statement as a string
+        #
+        # @api private
         def delete_statement(query)
           conditions_statement, bind_values = conditions_statement(query.conditions)
 
@@ -384,6 +407,8 @@ def columns_statement(properties, qualify)
         # Constructs joins clause
         #
         # @return [String] joins clause
+        #
+        # @api private
         def join_statement(previous_model, links, qualify)
           statement = ''
 
@@ -406,6 +431,8 @@ def join_statement(previous_model, links, qualify)
         # Constructs where clause
         #
         # @return [String] where clause
+        #
+        # @api private
         def conditions_statement(conditions, qualify = false)
           case conditions
             when Conditions::NotOperation
@@ -430,6 +457,8 @@ def conditions_statement(conditions, qualify = false)
         # Constructs order clause
         #
         # @return [String] order clause
+        #
+        # @api private
         def order_statement(order, qualify)
           statements = order.map do |order|
             statement = property_to_column_name(order.property, qualify)
@@ -440,6 +469,8 @@ def order_statement(order, qualify)
           statements.join(', ')
         end
 
+        # TODO: document
+        # @api private
         def negate_operation(operation, qualify)
           @negated = !@negated
           begin
@@ -449,6 +480,8 @@ def negate_operation(operation, qualify)
           end
         end
 
+        # TODO: document
+        # @api private
         def operation_statement(operation, qualify)
           statements  = []
           bind_values = []
@@ -475,6 +508,8 @@ def operation_statement(operation, qualify)
         # Constructs comparison clause
         #
         # @return [String] comparison clause
+        #
+        # @api private
         def comparison_statement(comparison, qualify)
           value = comparison.value
 
@@ -507,49 +542,69 @@ def comparison_statement(comparison, qualify)
           return "#{property_to_column_name(comparison.property, qualify)} #{operator} ?", [ value ]
         end
 
+        # TODO: document
+        # @api private
         def equality_operator(operand)
           operand.nil? ? 'IS' : '='
         end
 
+        # TODO: document
+        # @api private
         def inequality_operator(operand)
           operand.nil? ? 'IS NOT' : '<>'
         end
 
+        # TODO: document
+        # @api private
         def include_operator(operand)
           case operand
             when Array then 'IN'
             when Range then 'BETWEEN'
           end
         end
 
+        # TODO: document
+        # @api private
         def exclude_operator(operand)
           "NOT #{include_operator(operand)}"
         end
 
+        # TODO: document
+        # @api private
         def regexp_operator(operand)
           '~'
         end
 
+        # TODO: document
+        # @api private
         def not_regexp_operator(operand)
           '!~'
         end
 
+        # TODO: document
+        # @api private
         def like_operator(operand)
           'LIKE'
         end
 
+        # TODO: document
+        # @api private
         def unlike_operator(operand)
           'NOT LIKE'
         end
 
         # TODO: once the driver's quoting methods become public, have
         # this method delegate to them instead
+        # TODO: document
+        # @api private
         def quote_name(name)
           "\"#{name.gsub('"', '""')}\""
         end
 
         # TODO: once the driver's quoting methods become public, have
         # this method delegate to them instead
+        # TODO: document
+        # @api private
         def quote_value(value)
           case value
             when String

lib/dm-core/adapters/mysql_adapter.rb

@@ -9,18 +9,24 @@ class MysqlAdapter < DataObjectsAdapter
       module SQL #:nodoc:
         private
 
+        # TODO: document
+        # @api private
         def supports_default_values? #:nodoc:
           false
         end
 
         # TODO: once the driver's quoting methods become public, have
         # this method delegate to them instead
+        # TODO: document
+        # @api private
         def quote_name(name) #:nodoc:
           "`#{name.gsub('`', '``')}`"
         end
 
         # TODO: once the driver's quoting methods become public, have
         # this method delegate to them instead
+        # TODO: document
+        # @api private
         def quote_value(value) #:nodoc:
           case value
             when TrueClass  then super(1)
@@ -30,10 +36,14 @@ def quote_value(value) #:nodoc:
           end
         end
 
+        # TODO: document
+        # @api private
         def regexp_operator(operand)
           'REGEXP'
         end
 
+        # TODO: document
+        # @api private
         def not_regexp_operator(operand)
           'NOT REGEXP'
         end

lib/dm-core/adapters/postgres_adapter.rb

@@ -9,6 +9,8 @@ class PostgresAdapter < DataObjectsAdapter
       module SQL #:nodoc:
         private
 
+        # TODO: document
+        # @api private
         def supports_returning?
           true
         end

lib/dm-core/adapters/sqlite3_adapter.rb

@@ -11,6 +11,8 @@ module SQL #:nodoc:
 
         # TODO: once the driver's quoting methods become public, have
         # this method delegate to them instead
+        # TODO: document
+        # @api private
         def quote_value(value)
           case value
             when TrueClass  then super('t')

lib/dm-core/adapters/yaml_adapter.rb

@@ -1,9 +1,11 @@
+require 'yaml'
+require 'fileutils'
+
 module DataMapper
   module Adapters
     class YamlAdapter < AbstractAdapter
-      require 'yaml'
-      require 'fileutils'
-
+      # TODO: document
+      # @api semipublic
       def create(resources)
         update_records(resources.first.model) do |records|
           resources.each do |resource|
@@ -13,10 +15,14 @@ def create(resources)
         end
       end
 
+      # TODO: document
+      # @api semipublic
       def read(query)
         query.filter_records(records_for(query.model).dup)
       end
 
+      # TODO: document
+      # @api semipublic
       def update(attributes, collection)
         attributes = attributes_as_fields(attributes)
 
@@ -26,6 +32,8 @@ def update(attributes, collection)
         end
       end
 
+      # TODO: document
+      # @api semipublic
       def delete(collection)
         update_records(collection.model) do |records|
           records_to_delete = collection.query.filter_records(records.dup)
@@ -36,6 +44,8 @@ def delete(collection)
 
       private
 
+      # TODO: document
+      # @api semipublic
       def initialize(name, options = {})
         super
         @path = FileUtils.mkdir_p(@options[:path])