diff --git a/lib/dm-core/adapters.rb b/lib/dm-core/adapters.rb
index a000df9b2..828885c89 100644
--- a/lib/dm-core/adapters.rb
+++ b/lib/dm-core/adapters.rb
@@ -126,7 +126,6 @@ def load_adapter(name)
     end
 
     extendable do
-      # TODO: document
       # @api private
       def const_added(const_name)
       end
diff --git a/lib/dm-core/adapters/data_objects_adapter.rb b/lib/dm-core/adapters/data_objects_adapter.rb
index 23e2a649f..6a0381194 100644
--- a/lib/dm-core/adapters/data_objects_adapter.rb
+++ b/lib/dm-core/adapters/data_objects_adapter.rb
@@ -216,7 +216,6 @@ def delete(collection)
 
       protected
 
-      # TODO: document
       # @api private
       def normalized_uri
         @normalized_uri ||=
@@ -262,7 +261,6 @@ def close_connection(connection)
 
       private
 
-      # TODO: document
       # @api public
       def initialize(name, uri_or_options)
         super
@@ -273,14 +271,12 @@ def initialize(name, uri_or_options)
         end
       end
 
-      # TODO: document
       # @api private
       def connection_stack
         connection_stack_for = Thread.current[:dm_do_connection_stack] ||= {}
         connection_stack_for[self] ||= []
       end
 
-      # TODO: document
       # @api private
       def with_connection
         begin
@@ -298,7 +294,6 @@ def with_connection
       module SQL #:nodoc:
         IDENTIFIER_MAX_LENGTH = 128
 
-        # TODO: document
         # @api semipublic
         def property_to_column_name(property, qualify, qualifier = nil)
           if qualify
@@ -492,13 +487,11 @@ def conditions_statement(conditions, qualify = false)
           end
         end
 
-        # TODO: document
         # @api private
         def supports_subquery?(*)
           true
         end
 
-        # TODO: document
         # @api private
         def subquery(*args)
           if args.first.repository.name == name && supports_subquery?(*args)
@@ -508,7 +501,6 @@ def subquery(*args)
           end
         end
 
-        # TODO: document
         # @api private
         def subquery_statement(query, source_key, target_key, qualify)
           query = query.merge(:fields => source_key, :unique => false)
@@ -526,7 +518,6 @@ def subquery_statement(query, source_key, target_key, qualify)
           return statement, bind_values
         end
 
-        # TODO: document
         # @api private
         def subquery_execute(query, source_key, target_key, qualify)
           query = query.merge(:fields => source_key)
@@ -558,7 +549,6 @@ def order_statement(order, qualify, qualifier = nil)
           statements.join(', ')
         end
 
-        # TODO: document
         # @api private
         def negate_operation(operand, qualify)
           @negated = !@negated
@@ -569,7 +559,6 @@ def negate_operation(operand, qualify)
           end
         end
 
-        # TODO: document
         # @api private
         def operation_statement(operation, qualify)
           statements  = []
@@ -652,19 +641,16 @@ def comparison_operator(comparison)
           end
         end
 
-        # TODO: document
         # @api private
         def equality_operator(property, operand)
           operand.nil? ? 'IS' : '='
         end
 
-        # TODO: document
         # @api private
         def inequality_operator(property, operand)
           operand.nil? ? 'IS NOT' : '<>'
         end
 
-        # TODO: document
         # @api private
         def include_operator(property, operand)
           case operand
@@ -673,37 +659,31 @@ def include_operator(property, operand)
           end
         end
 
-        # TODO: document
         # @api private
         def exclude_operator(property, operand)
           "NOT #{include_operator(property, 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: document
         # @api private
         def quote_name(name)
           "\"#{name[0, self.class::IDENTIFIER_MAX_LENGTH].gsub('"', '""')}\""
diff --git a/lib/dm-core/adapters/mysql_adapter.rb b/lib/dm-core/adapters/mysql_adapter.rb
index 53908831c..f3ccee748 100644
--- a/lib/dm-core/adapters/mysql_adapter.rb
+++ b/lib/dm-core/adapters/mysql_adapter.rb
@@ -10,13 +10,11 @@ module SQL #:nodoc:
 
         private
 
-        # TODO: document
         # @api private
         def supports_default_values? #:nodoc:
           false
         end
 
-        # TODO: document
         # @api private
         def supports_subquery?(query, source_key, target_key, qualify)
           # TODO: renable once query does not include target_model for deletes and updates
@@ -25,19 +23,16 @@ def supports_subquery?(query, source_key, target_key, qualify)
           false
         end
 
-        # TODO: document
         # @api private
         def regexp_operator(operand)
           'REGEXP'
         end
 
-        # TODO: document
         # @api private
         def not_regexp_operator(operand)
           'NOT REGEXP'
         end
 
-        # TODO: document
         # @api private
         def quote_name(name)
           "`#{name[0, self.class::IDENTIFIER_MAX_LENGTH].gsub('`', '``')}`"
diff --git a/lib/dm-core/adapters/oracle_adapter.rb b/lib/dm-core/adapters/oracle_adapter.rb
index ceff417c9..9d8fcf2f9 100644
--- a/lib/dm-core/adapters/oracle_adapter.rb
+++ b/lib/dm-core/adapters/oracle_adapter.rb
@@ -60,7 +60,6 @@ def default_values_clause
           'VALUES (DEFAULT)'
         end
 
-        # TODO: document
         # @api private
         def supports_returning?
           true
@@ -164,7 +163,6 @@ def add_limit_offset!(statement, limit, offset, bind_values)
           end
         end
 
-        # TODO: document
         # @api private
         # Oracle does not allow " in table or column names therefore substitute them with underscore
         def quote_name(name)
@@ -199,7 +197,6 @@ def inequality_operator(property, operand)
           end
         end
 
-        # TODO: document
         # @api private
         def include_operator(property, operand)
           operator = case operand
@@ -213,7 +210,6 @@ def include_operator(property, operand)
           end
         end
 
-        # TODO: document
         # @api private
         def exclude_operator(property, operand)
           operator = case operand
@@ -227,13 +223,11 @@ def exclude_operator(property, operand)
           end
         end
 
-        # TODO: document
         # @api private
         def regexp_operator(operand)
           'REGEXP_LIKE(%s, ?)'
         end
 
-        # TODO: document
         # @api private
         def not_regexp_operator(operand)
           'NOT REGEXP_LIKE(%s, ?)'
diff --git a/lib/dm-core/adapters/postgres_adapter.rb b/lib/dm-core/adapters/postgres_adapter.rb
index 79cba5cce..f6519c4b6 100644
--- a/lib/dm-core/adapters/postgres_adapter.rb
+++ b/lib/dm-core/adapters/postgres_adapter.rb
@@ -8,7 +8,6 @@ class PostgresAdapter < DataObjectsAdapter
       module SQL #:nodoc:
         private
 
-        # TODO: document
         # @api private
         def supports_returning?
           true
diff --git a/lib/dm-core/adapters/sqlite3_adapter.rb b/lib/dm-core/adapters/sqlite3_adapter.rb
index 9aebff1b7..25e299164 100644
--- a/lib/dm-core/adapters/sqlite3_adapter.rb
+++ b/lib/dm-core/adapters/sqlite3_adapter.rb
@@ -5,7 +5,6 @@
 module DataMapper
   module Adapters
     class Sqlite3Adapter < DataObjectsAdapter
-      # TODO: document
       # @api private
       def supports_subquery?(query, source_key, target_key, qualify)
         # SQLite3 cannot match a subquery against more than one column
diff --git a/lib/dm-core/adapters/sqlserver_adapter.rb b/lib/dm-core/adapters/sqlserver_adapter.rb
index 0381783bb..402705b69 100644
--- a/lib/dm-core/adapters/sqlserver_adapter.rb
+++ b/lib/dm-core/adapters/sqlserver_adapter.rb
@@ -86,7 +86,6 @@ def add_limit_offset!(statement, limit, offset, bind_values)
           end
         end
 
-        # TODO: document
         # @api private
         # TODO: Not actually supported out of the box. Is theoretically possible
         # via CLR integration, custom functions.
@@ -94,7 +93,6 @@ def regexp_operator(operand)
           'REGEXP'
         end
 
-        # TODO: document
         # @api private
         # TODO: Not actually supported out of the box. Is theoretically possible
         # via CLR integration, custom functions.
diff --git a/lib/dm-core/adapters/yaml_adapter.rb b/lib/dm-core/adapters/yaml_adapter.rb
index 114e7542f..5d8ca8397 100644
--- a/lib/dm-core/adapters/yaml_adapter.rb
+++ b/lib/dm-core/adapters/yaml_adapter.rb
@@ -4,7 +4,6 @@
 module DataMapper
   module Adapters
     class YamlAdapter < AbstractAdapter
-      # TODO: document
       # @api semipublic
       def create(resources)
         update_records(resources.first.model) do |records|
@@ -15,13 +14,11 @@ 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)
@@ -32,7 +29,6 @@ def update(attributes, collection)
         end
       end
 
-      # TODO: document
       # @api semipublic
       def delete(collection)
         update_records(collection.model) do |records|
@@ -44,7 +40,6 @@ def delete(collection)
 
       private
 
-      # TODO: document
       # @api semipublic
       def initialize(name, options = {})
         super
diff --git a/lib/dm-core/associations/many_to_one.rb b/lib/dm-core/associations/many_to_one.rb
index ca7605693..91a95d73b 100644
--- a/lib/dm-core/associations/many_to_one.rb
+++ b/lib/dm-core/associations/many_to_one.rb
@@ -6,27 +6,21 @@ module ManyToOne #:nodoc:
       class Relationship < Associations::Relationship
         OPTIONS = superclass::OPTIONS.dup << :nullable
 
-        # TODO: document
         # @api semipublic
         alias source_repository_name child_repository_name
 
-        # TODO: document
         # @api semipublic
         alias source_model child_model
 
-        # TODO: document
         # @api semipublic
         alias target_repository_name parent_repository_name
 
-        # TODO: document
         # @api semipublic
         alias target_model parent_model
 
-        # TODO: document
         # @api semipublic
         alias target_key parent_key
 
-        # TODO: document
         # @api semipublic
         def nullable?
           @nullable
@@ -57,7 +51,6 @@ def child_key
           @child_key = properties.class.new(child_key).freeze
         end
 
-        # TODO: document
         # @api semipublic
         alias source_key child_key
 
@@ -187,7 +180,6 @@ def inverse_name
           super || Extlib::Inflection.underscore(Extlib::Inflection.demodulize(source_model.name)).pluralize.to_sym
         end
 
-        # TODO: document
         # @api private
         def child_key_options(parent_property)
           options = parent_property.options.only(:length, :precision, :scale).update(:index => name, :nullable => nullable?)
@@ -199,7 +191,6 @@ def child_key_options(parent_property)
           options
         end
 
-        # TODO: document
         # @api private
         def child_properties
           child_key.map { |property| property.name }
diff --git a/lib/dm-core/associations/one_to_many.rb b/lib/dm-core/associations/one_to_many.rb
index 47ad7fdaf..5e89f538a 100644
--- a/lib/dm-core/associations/one_to_many.rb
+++ b/lib/dm-core/associations/one_to_many.rb
@@ -2,33 +2,26 @@ module DataMapper
   module Associations
     module OneToMany #:nodoc:
       class Relationship < Associations::Relationship
-        # TODO: document
         # @api semipublic
         alias target_repository_name child_repository_name
 
-        # TODO: document
         # @api semipublic
         alias target_model child_model
 
-        # TODO: document
         # @api semipublic
         alias source_repository_name parent_repository_name
 
-        # TODO: document
         # @api semipublic
         alias source_model parent_model
 
-        # TODO: document
         # @api semipublic
         alias source_key parent_key
 
-        # TODO: document
         # @api semipublic
         def child_key
           inverse.child_key
         end
 
-        # TODO: document
         # @api semipublic
         alias target_key child_key
 
@@ -84,7 +77,6 @@ def set(source, targets)
 
         private
 
-        # TODO: document
         # @api semipublic
         def initialize(name, target_model, source_model, options = {})
           target_model ||= Extlib::Inflection.camelize(name.to_s.singular)
@@ -150,7 +142,6 @@ def inverse_name
           super || Extlib::Inflection.underscore(Extlib::Inflection.demodulize(source_model.name)).to_sym
         end
 
-        # TODO: document
         # @api private
         def child_properties
           super || parent_key.map do |parent_property|
@@ -160,15 +151,12 @@ def child_properties
       end # class Relationship
 
       class Collection < DataMapper::Collection
-        # TODO: document
         # @api private
         attr_accessor :relationship
 
-        # TODO: document
         # @api private
         attr_accessor :source
 
-        # TODO: document
         # @api public
         def reload(*)
           assert_source_saved 'The source must be saved before reloading the collection'
@@ -261,14 +249,12 @@ def destroy!
 
         private
 
-        # TODO: document
         # @api private
         def _create(*)
           assert_source_saved 'The source must be saved before creating a resource'
           super
         end
 
-        # TODO: document
         # @api private
         def _save(safe, resources = {})
           assert_source_saved 'The source must be saved before saving the collection'
@@ -277,7 +263,6 @@ def _save(safe, resources = {})
           @removed.all? { |resource| resource.destroyed? || resource.__send__(:_save, safe, resources) } && super
         end
 
-        # TODO: document
         # @api private
         def lazy_load
           if source.saved?
@@ -285,7 +270,6 @@ def lazy_load
           end
         end
 
-        # TODO: document
         # @api private
         def new_collection(query, resources = nil, &block)
           collection = self.class.new(query, &block)
@@ -303,7 +287,6 @@ def new_collection(query, resources = nil, &block)
           collection
         end
 
-        # TODO: document
         # @api private
         def resource_added(resource)
           resource = initialize_resource(resource)
@@ -311,14 +294,12 @@ def resource_added(resource)
           super
         end
 
-        # TODO: document
         # @api private
         def resource_removed(resource)
           inverse_set(resource, nil)
           super
         end
 
-        # TODO: document
         # @api private
         def inverse_set(source, target)
           unless source.readonly?
@@ -326,7 +307,6 @@ def inverse_set(source, target)
           end
         end
 
-        # TODO: document
         # @api private
         def assert_source_saved(message)
           unless source.saved?
diff --git a/lib/dm-core/migrations.rb b/lib/dm-core/migrations.rb
index f29356291..504efefef 100644
--- a/lib/dm-core/migrations.rb
+++ b/lib/dm-core/migrations.rb
@@ -22,7 +22,6 @@ def auto_migrate!(repository_name = nil)
         auto_migrate_up!(repository_name)
       end
 
-      # TODO: document
       # @api public
       def auto_upgrade!(repository_name = nil)
         repository_execute(:auto_upgrade!, repository_name)
@@ -30,19 +29,16 @@ def auto_upgrade!(repository_name = nil)
 
       private
 
-      # TODO: document
       # @api private
       def auto_migrate_down!(repository_name)
         repository_execute(:auto_migrate_down!, repository_name)
       end
 
-      # TODO: document
       # @api private
       def auto_migrate_up!(repository_name)
         repository_execute(:auto_migrate_up!, repository_name)
       end
 
-      # TODO: document
       # @api private
       def repository_execute(method, repository_name)
         DataMapper::Model.descendants.each do |model|
@@ -52,7 +48,6 @@ def repository_execute(method, repository_name)
     end
 
     module DataObjectsAdapter
-      # TODO: document
       # @api private
       def self.included(base)
         base.extend ClassMethods
@@ -108,7 +103,6 @@ def field_exists?(storage_name, column_name)
         select(statement, schema_name, storage_name, column_name).first > 0
       end
 
-      # TODO: document
       # @api semipublic
       def upgrade_model_storage(model)
         properties = model.properties_with_subclasses(name)
@@ -133,7 +127,6 @@ def upgrade_model_storage(model)
         end
       end
 
-      # TODO: document
       # @api semipublic
       def create_model_storage(model)
         properties = model.properties_with_subclasses(name)
@@ -155,7 +148,6 @@ def create_model_storage(model)
         true
       end
 
-      # TODO: document
       # @api semipublic
       def destroy_model_storage(model)
         return true unless supports_drop_table_if_exists? || storage_exists?(model.storage_name(name))
@@ -174,25 +166,21 @@ def supports_serial?
           false
         end
 
-        # TODO: document
         # @api private
         def supports_drop_table_if_exists?
           false
         end
 
-        # TODO: document
         # @api private
         def schema_name
           raise NotImplementedError, "#{self.class}#schema_name not implemented"
         end
 
-        # TODO: document
         # @api private
         def alter_table_add_column_statement(connection, table_name, schema_hash)
           "ALTER TABLE #{quote_name(table_name)} ADD COLUMN #{property_schema_statement(connection, schema_hash)}"
         end
 
-        # TODO: document
         # @api private
         def create_table_statement(connection, model, properties)
           statement = <<-SQL.compress_lines
@@ -204,7 +192,6 @@ def create_table_statement(connection, model, properties)
           statement
         end
 
-        # TODO: document
         # @api private
         def drop_table_statement(model)
           if supports_drop_table_if_exists?
@@ -214,7 +201,6 @@ def drop_table_statement(model)
           end
         end
 
-        # TODO: document
         # @api private
         def create_index_statements(model)
           table_name = model.storage_name(name)
@@ -226,7 +212,6 @@ def create_index_statements(model)
           end
         end
 
-        # TODO: document
         # @api private
         def create_unique_index_statements(model)
           table_name = model.storage_name(name)
@@ -238,7 +223,6 @@ def create_unique_index_statements(model)
           end
         end
 
-        # TODO: document
         # @api private
         def property_schema_hash(property)
           schema = (self.class.type_map[property.type] || self.class.type_map[property.primitive]).merge(:name => property.field)
@@ -267,7 +251,6 @@ def property_schema_hash(property)
           schema
         end
 
-        # TODO: document
         # @api private
         def property_schema_statement(connection, schema)
           statement = quote_name(schema[:name])
@@ -321,19 +304,16 @@ module MysqlAdapter
       DEFAULT_CHARACTER_SET = 'utf8'.freeze
       DEFAULT_COLLATION     = 'utf8_unicode_ci'.freeze
 
-      # TODO: document
       # @api private
       def self.included(base)
         base.extend ClassMethods
       end
 
-      # TODO: document
       # @api semipublic
       def storage_exists?(storage_name)
         select('SHOW TABLES LIKE ?', storage_name).first == storage_name
       end
 
-      # TODO: document
       # @api semipublic
       def field_exists?(storage_name, field)
         result = select("SHOW COLUMNS FROM #{quote_name(storage_name)} LIKE ?", field).first
@@ -343,19 +323,16 @@ def field_exists?(storage_name, field)
       module SQL #:nodoc:
 #        private  ## This cannot be private for current migrations
 
-        # TODO: document
         # @api private
         def supports_serial?
           true
         end
 
-        # TODO: document
         # @api private
         def supports_drop_table_if_exists?
           true
         end
 
-        # TODO: document
         # @api private
         def schema_name
           # TODO: is there a cleaner way to find out the current DB we are connected to?
@@ -365,13 +342,11 @@ def schema_name
         # TODO: update dkubb/dm-more/dm-migrations to use schema_name and remove this
         alias db_name schema_name
 
-        # TODO: document
         # @api private
         def create_table_statement(connection, model, properties)
           "#{super} ENGINE = #{DEFAULT_ENGINE} CHARACTER SET #{character_set} COLLATE #{collation}"
         end
 
-        # TODO: document
         # @api private
         def property_schema_hash(property)
           schema = super
@@ -388,7 +363,6 @@ def property_schema_hash(property)
           schema
         end
 
-        # TODO: document
         # @api private
         def property_schema_statement(connection, schema)
           statement = super
@@ -400,19 +374,16 @@ def property_schema_statement(connection, schema)
           statement
         end
 
-        # TODO: document
         # @api private
         def character_set
           @character_set ||= show_variable('character_set_connection') || DEFAULT_CHARACTER_SET
         end
 
-        # TODO: document
         # @api private
         def collation
           @collation ||= show_variable('collation_connection') || DEFAULT_COLLATION
         end
 
-        # TODO: document
         # @api private
         def show_variable(name)
           result = select('SHOW VARIABLES LIKE ?', name).first
@@ -575,25 +546,21 @@ def type_map
     end # module MysqlAdapter
 
     module PostgresAdapter
-      # TODO: document
       # @api private
       def self.included(base)
         base.extend ClassMethods
       end
 
-      # TODO: document
       # @api semipublic
       def upgrade_model_storage(model)
         without_notices { super }
       end
 
-      # TODO: document
       # @api semipublic
       def create_model_storage(model)
         without_notices { super }
       end
 
-      # TODO: document
       # @api semipublic
       def destroy_model_storage(model)
         if supports_drop_table_if_exists?
@@ -606,25 +573,21 @@ def destroy_model_storage(model)
       module SQL #:nodoc:
 #        private  ## This cannot be private for current migrations
 
-        # TODO: document
         # @api private
         def supports_drop_table_if_exists?
           @supports_drop_table_if_exists ||= postgres_version >= '8.2'
         end
 
-        # TODO: document
         # @api private
         def schema_name
           @schema_name ||= select('SELECT current_schema()').first.freeze
         end
 
-        # TODO: document
         # @api private
         def postgres_version
           @postgres_version ||= select('SELECT version()').first.split[1].freeze
         end
 
-        # TODO: document
         # @api private
         def without_notices
           # execute the block with NOTICE messages disabled
@@ -636,7 +599,6 @@ def without_notices
           end
         end
 
-        # TODO: document
         # @api private
         def property_schema_hash(property)
           schema = super
@@ -722,19 +684,16 @@ def type_map
     end # module PostgresAdapter
 
     module Sqlite3Adapter
-      # TODO: document
       # @api private
       def self.included(base)
         base.extend ClassMethods
       end
 
-      # TODO: document
       # @api semipublic
       def storage_exists?(storage_name)
         table_info(storage_name).any?
       end
 
-      # TODO: document
       # @api semipublic
       def field_exists?(storage_name, column_name)
         table_info(storage_name).any? do |row|
@@ -745,25 +704,21 @@ def field_exists?(storage_name, column_name)
       module SQL #:nodoc:
 #        private  ## This cannot be private for current migrations
 
-        # TODO: document
         # @api private
         def supports_serial?
           @supports_serial ||= sqlite_version >= '3.1.0'
         end
 
-        # TODO: document
         # @api private
         def supports_drop_table_if_exists?
           @supports_drop_table_if_exists ||= sqlite_version >= '3.3.0'
         end
 
-        # TODO: document
         # @api private
         def table_info(table_name)
           select("PRAGMA table_info(#{quote_name(table_name)})")
         end
 
-        # TODO: document
         # @api private
         def create_table_statement(connection, model, properties)
           statement = <<-SQL.compress_lines
@@ -782,7 +737,6 @@ def create_table_statement(connection, model, properties)
           statement
         end
 
-        # TODO: document
         # @api private
         def property_schema_statement(connection, schema)
           statement = super
@@ -794,7 +748,6 @@ def property_schema_statement(connection, schema)
           statement
         end
 
-        # TODO: document
         # @api private
         def sqlite_version
           @sqlite_version ||= select('SELECT sqlite_version(*)').first.freeze
@@ -816,13 +769,11 @@ def type_map
     end # module Sqlite3Adapter
 
     module OracleAdapter
-      # TODO: document
       # @api private
       def self.included(base)
         base.extend ClassMethods
       end
 
-      # TODO: document
       # @api semipublic
       def storage_exists?(storage_name)
         statement = <<-SQL.compress_lines
@@ -835,7 +786,6 @@ def storage_exists?(storage_name)
         select(statement, schema_name, oracle_upcase(storage_name)).first > 0
       end
 
-      # TODO: document
       # @api semipublic
       def sequence_exists?(sequence_name)
         return false unless sequence_name
@@ -849,7 +799,6 @@ def sequence_exists?(sequence_name)
         select(statement, schema_name, oracle_upcase(sequence_name)).first > 0
       end
 
-      # TODO: document
       # @api semipublic
       def field_exists?(storage_name, field_name)
         statement = <<-SQL.compress_lines
@@ -863,7 +812,6 @@ def field_exists?(storage_name, field_name)
         select(statement, schema_name, oracle_upcase(storage_name), oracle_upcase(field_name)).first > 0
       end
 
-      # TODO: document
       # @api semipublic
       def storage_fields(storage_name)
         statement = <<-SQL.compress_lines
@@ -876,7 +824,6 @@ def storage_fields(storage_name)
         select(statement, schema_name, oracle_upcase(storage_name))
       end
 
-      # TODO: document
       # @api semipublic
       def create_model_storage(model)
         properties = model.properties_with_subclasses(name)
@@ -919,7 +866,6 @@ def create_model_storage(model)
         true
       end
 
-      # TODO: document
       # @api semipublic
       def destroy_model_storage(model, forced = false)
         table_name = model.storage_name(name)
@@ -973,13 +919,11 @@ def oracle_upcase(name)
       module SQL #:nodoc:
 #        private  ## This cannot be private for current migrations
 
-        # TODO: document
         # @api private
         def schema_name
           @schema_name ||= select("SELECT SYS_CONTEXT('userenv','current_schema') FROM dual").first.freeze
         end
 
-        # TODO: document
         # @api private
         def create_sequence_statements(model)
           table_name = model.storage_name(name)
@@ -1010,7 +954,6 @@ def create_sequence_statements(model)
           statements
         end
 
-        # TODO: document
         # @api private
         def drop_sequence_statement(model)
           if sequence_name = model_sequence_name(model)
@@ -1020,7 +963,6 @@ def drop_sequence_statement(model)
           end
         end
 
-        # TODO: document
         # @api private
         def reset_sequence_statement(model)
           if sequence_name = model_sequence_name(model)
@@ -1040,13 +982,11 @@ def reset_sequence_statement(model)
 
         end
 
-        # TODO: document
         # @api private
         def truncate_table_statement(model)
           "TRUNCATE TABLE #{quote_name(model.storage_name(name))}"
         end
 
-        # TODO: document
         # @api private
         def delete_table_statement(model)
           "DELETE FROM #{quote_name(model.storage_name(name))}"
@@ -1139,19 +1079,16 @@ def auto_migrate_reset_sequences(value = :not_specified)
    module SqlserverAdapter
       DEFAULT_CHARACTER_SET = 'utf8'.freeze
 
-      # TODO: document
       # @api private
       def self.included(base)
         base.extend ClassMethods
       end
 
-      # TODO: document
       # @api semipublic
       def storage_exists?(storage_name)
         select("SELECT name FROM sysobjects WHERE name LIKE ?", storage_name).first == storage_name
       end
 
-      # TODO: document
       # @api semipublic
       def field_exists?(storage_name, field_name)
         result = select("SELECT c.name FROM sysobjects as o JOIN syscolumns AS c ON o.id = c.id WHERE o.name = #{quote_name(storage_name)} AND c.name LIKE ?", field_name).first
@@ -1161,19 +1098,16 @@ def field_exists?(storage_name, field_name)
       module SQL #:nodoc:
 #        private  ## This cannot be private for current migrations
 
-        # TODO: document
         # @api private
         def supports_serial?
           true
         end
 
-        # TODO: document
         # @api private
         def supports_drop_table_if_exists?
           false
         end
 
-        # TODO: document
         # @api private
         def schema_name
           # TODO: is there a cleaner way to find out the current DB we are connected to?
@@ -1184,7 +1118,6 @@ def schema_name
 
         alias db_name schema_name
 
-        # TODO: document
         # @api private
         def create_table_statement(connection, model, properties)
           statement = <<-SQL.compress_lines
@@ -1200,7 +1133,6 @@ def create_table_statement(connection, model, properties)
           statement
         end
 
-        # TODO: document
         # @api private
         def property_schema_hash(property)
           schema = super
@@ -1216,7 +1148,6 @@ def property_schema_hash(property)
           schema
         end
 
-        # TODO: document
         # @api private
         def property_schema_statement(connection, schema)
           if supports_serial? && schema[:serial]
@@ -1237,19 +1168,16 @@ def property_schema_statement(connection, schema)
           statement
         end
 
-        # TODO: document
         # @api private
         def character_set
           @character_set ||= show_variable('character_set_connection') || DEFAULT_CHARACTER_SET
         end
 
-        # TODO: document
         # @api private
         def collation
           @collation ||= show_variable('collation_connection') || DEFAULT_COLLATION
         end
 
-        # TODO: document
         # @api private
         def show_variable(name)
           raise "SqlserverAdapter#show_variable: Not implemented"
@@ -1323,7 +1251,6 @@ def storage_exists?(storage_name)
         end
       end
 
-      # TODO: document
       # @api semipublic
       def upgrade_model_storage(model)
         if adapter.respond_to?(:upgrade_model_storage)
@@ -1331,7 +1258,6 @@ def upgrade_model_storage(model)
         end
       end
 
-      # TODO: document
       # @api semipublic
       def create_model_storage(model)
         if adapter.respond_to?(:create_model_storage)
@@ -1339,7 +1265,6 @@ def create_model_storage(model)
         end
       end
 
-      # TODO: document
       # @api semipublic
       def destroy_model_storage(model)
         if adapter.respond_to?(:destroy_model_storage)
@@ -1366,13 +1291,11 @@ def auto_upgrade!
     end # module Repository
 
     module Model
-      # TODO: document
       # @api private
       def self.included(mod)
         mod.descendants.each { |model| model.extend self }
       end
 
-      # TODO: document
       # @api semipublic
       def storage_exists?(repository_name = default_repository_name)
         repository(repository_name).storage_exists?(storage_name(repository_name))
@@ -1440,7 +1363,6 @@ def auto_migrate_up!(repository_name = self.repository_name)
   module Adapters
     extendable do
 
-      # TODO: document
       # @api private
       def const_added(const_name)
         if DataMapper::Migrations.const_defined?(const_name)
diff --git a/lib/dm-core/model/hook.rb b/lib/dm-core/model/hook.rb
index 87a0b7e8b..539a4370d 100644
--- a/lib/dm-core/model/hook.rb
+++ b/lib/dm-core/model/hook.rb
@@ -10,7 +10,6 @@ def self.included(model)
       end
 
       module Methods
-        # TODO: document
         # @api public
         def before(target_method, *args, &block)
           remap_target_method(target_method).each do |target_method|
@@ -18,7 +17,6 @@ def before(target_method, *args, &block)
           end
         end
 
-        # TODO: document
         # @api public
         def after(target_method, *args, &block)
           remap_target_method(target_method).each do |target_method|
@@ -28,7 +26,6 @@ def after(target_method, *args, &block)
 
         private
 
-        # TODO: document
         # @api private
         def remap_target_method(target_method)
           case target_method
diff --git a/lib/dm-core/model/property.rb b/lib/dm-core/model/property.rb
index 1520bb745..b972419a4 100644
--- a/lib/dm-core/model/property.rb
+++ b/lib/dm-core/model/property.rb
@@ -129,7 +129,6 @@ def key(repository_name = default_repository_name)
         properties(repository_name).key
       end
 
-      # TODO: document
       # @api public
       def serial(repository_name = default_repository_name)
         key(repository_name).detect { |property| property.serial? }
@@ -149,7 +148,6 @@ def field_naming_convention(repository_name = default_storage_name)
         @field_naming_conventions[repository_name] ||= repository(repository_name).adapter.field_naming_convention
       end
 
-      # TODO: document
       # @api private
       def properties_with_subclasses(repository_name = default_repository_name)
         properties = PropertySet.new
@@ -163,19 +161,16 @@ def properties_with_subclasses(repository_name = default_repository_name)
         properties
       end
 
-      # TODO: document
       # @api private
       def paranoid_properties
         @paranoid_properties
       end
 
-      # TODO: document
       # @api private
       def set_paranoid_property(name, &block)
         paranoid_properties[name] = block
       end
 
-      # TODO: document
       # @api private
       def key_conditions(repository, key)
         self.key(repository.name).zip(key.nil? ? [] : key).to_hash
@@ -232,7 +227,6 @@ def #{writer_name}(value)
       end
 
       chainable do
-        # TODO: document
         # @api public
         def method_missing(method, *args, &block)
           if property = properties(repository_name)[method]
diff --git a/lib/dm-core/model/relationship.rb b/lib/dm-core/model/relationship.rb
index c08d42fb6..f01ce7ba3 100644
--- a/lib/dm-core/model/relationship.rb
+++ b/lib/dm-core/model/relationship.rb
@@ -318,7 +318,6 @@ def assert_valid_options(options)
       end
 
       chainable do
-        # TODO: document
         # @api public
         def method_missing(method, *args, &block)
           if relationship = relationships(repository_name)[method]
diff --git a/lib/dm-core/model/scope.rb b/lib/dm-core/model/scope.rb
index fc49b6e83..912e8150c 100644
--- a/lib/dm-core/model/scope.rb
+++ b/lib/dm-core/model/scope.rb
@@ -10,7 +10,6 @@ module Model
     # It is also possible to get exclusive scope access
     # using +with_exclusive_scope+
     module Scope
-      # TODO: document
       # @api private
       def default_scope(repository_name = default_repository_name)
         @default_scope ||= {}
@@ -29,7 +28,6 @@ def query
         Query.new(repository, self, current_scope).freeze
       end
 
-      # TODO: document
       # @api private
       def current_scope
         scope_stack.last || default_scope(repository.name)
diff --git a/lib/dm-core/property.rb b/lib/dm-core/property.rb
index 5d27428b6..c3e172da4 100644
--- a/lib/dm-core/property.rb
+++ b/lib/dm-core/property.rb
@@ -597,13 +597,11 @@ def lazy_load(resource)
       resource.__send__(:lazy_load, lazy_load_properties)
     end
 
-    # TODO: document
     # @api private
     def lazy_load_properties
       @lazy_load_properties ||= properties.in_context(lazy? ? [ self ] : properties.defaults)
     end
 
-    # TODO: document
     # @api private
     def properties
       @properties ||= model.properties(repository_name)
@@ -747,7 +745,6 @@ def primitive?(value)
 
     private
 
-    # TODO: document
     # @api semipublic
     def initialize(model, name, type, options = {})
       assert_kind_of 'model',   model,   Model
@@ -850,7 +847,6 @@ def initialize(model, name, type, options = {})
       @model.auto_generate_validations(self) if @model.respond_to?(:auto_generate_validations)
     end
 
-    # TODO: document
     # @api private
     def assert_valid_options(options)
       if (unknown_keys = options.keys - OPTIONS).any?
diff --git a/lib/dm-core/property_set.rb b/lib/dm-core/property_set.rb
index ba11e47c5..80320cca3 100755
--- a/lib/dm-core/property_set.rb
+++ b/lib/dm-core/property_set.rb
@@ -10,7 +10,6 @@ class PropertySet < Array
     deprecate :slice,         :values_at
     deprecate :add,           :<<
 
-    # TODO: document
     # @api semipublic
     def [](name)
       @properties[name]
@@ -19,25 +18,21 @@ def [](name)
     alias superclass_slice []=
     private :superclass_slice
 
-    # TODO: document
     # @api semipublic
     def []=(name, property)
       self << property
     end
 
-    # TODO: document
     # @api semipublic
     def named?(name)
       @properties.key?(name)
     end
 
-    # TODO: document
     # @api semipublic
     def values_at(*names)
       @properties.values_at(*names)
     end
 
-    # TODO: document
     # @api semipublic
     def <<(property)
       if named?(property.name)
@@ -49,38 +44,32 @@ def <<(property)
       end
     end
 
-    # TODO: document
     # @api semipublic
     def include?(property)
       named?(property.name)
     end
 
-    # TODO: document
     # @api semipublic
     def index(property)
       each_index { |index| break index if at(index).name == property.name }
     end
 
     # TODO: make PropertySet#reject return a PropertySet instance
-    # TODO: document
     # @api semipublic
     def defaults
       @defaults ||= self.class.new(key | [ discriminator ].compact | reject { |property| property.lazy? }).freeze
     end
 
-    # TODO: document
     # @api semipublic
     def key
       @key ||= self.class.new(select { |property| property.key? }).freeze
     end
 
-    # TODO: document
     # @api semipublic
     def discriminator
       @discriminator ||= detect { |property| property.type == Types::Discriminator }
     end
 
-    # TODO: document
     # @api semipublic
     def indexes
       index_hash = {}
@@ -88,7 +77,6 @@ def indexes
       index_hash
     end
 
-    # TODO: document
     # @api semipublic
     def unique_indexes
       index_hash = {}
@@ -96,49 +84,41 @@ def unique_indexes
       index_hash
     end
 
-    # TODO: document
     # @api semipublic
     def get(resource)
       map { |property| property.get(resource) }
     end
 
-    # TODO: document
     # @api semipublic
     def get!(resource)
       map { |property| property.get!(resource) }
     end
 
-    # TODO: document
     # @api semipublic
     def set(resource, values)
       zip(values) { |property, value| property.set(resource, value) }
     end
 
-    # TODO: document
     # @api semipublic
     def set!(resource, values)
       zip(values) { |property, value| property.set!(resource, value) }
     end
 
-    # TODO: document
     # @api semipublic
     def loaded?(resource)
       all? { |property| property.loaded?(resource) }
     end
 
-    # TODO: document
     # @api semipublic
     def valid?(values)
       zip(values.nil? ? [] : values).all? { |property, value| property.valid?(value) }
     end
 
-    # TODO: document
     # @api semipublic
     def typecast(values)
       zip(values.nil? ? [] : values).map { |property, value| property.typecast(value) }
     end
 
-    # TODO: document
     # @api private
     def property_contexts(property)
       contexts = []
@@ -148,13 +128,11 @@ def property_contexts(property)
       contexts
     end
 
-    # TODO: document
     # @api private
     def lazy_context(context)
       lazy_contexts[context] ||= []
     end
 
-    # TODO: document
     # @api private
     def in_context(properties)
       properties_in_context = properties.map do |property|
@@ -170,40 +148,34 @@ def in_context(properties)
 
     private
 
-    # TODO: document
     # @api semipublic
     def initialize(*)
       super
       @properties = map { |property| [ property.name, property ] }.to_mash
     end
 
-    # TODO: document
     # @api private
     def initialize_copy(*)
       super
       @properties = @properties.dup
     end
 
-    # TODO: document
     # @api private
     def add_property(property)
       clear_cache
       @properties[property.name] = property
     end
 
-    # TODO: document
     # @api private
     def clear_cache
       @defaults, @key, @discriminator = nil
     end
 
-    # TODO: document
     # @api private
     def lazy_contexts
       @lazy_contexts ||= {}
     end
 
-    # TODO: document
     # @api private
     def parse_index(index, property, index_hash)
       case index
diff --git a/lib/dm-core/query.rb b/lib/dm-core/query.rb
index c90206c20..de081814b 100644
--- a/lib/dm-core/query.rb
+++ b/lib/dm-core/query.rb
@@ -1025,7 +1025,6 @@ def append_condition(subject, bind_value, model = self.model, operator = :eql)
       end
     end
 
-    # TODO: document
     # @api private
     def append_property_condition(property, bind_value, operator)
       negated = operator == :not
@@ -1062,13 +1061,11 @@ def equality_operator_for_type(bind_value)
       end
     end
 
-    # TODO: document
     # @api private
     def append_symbol_condition(symbol, bind_value, model, operator)
       append_condition(symbol.to_s, bind_value, model, operator)
     end
 
-    # TODO: document
     # @api private
     def append_string_condition(string, bind_value, model, operator)
       if string.include?('.')
@@ -1088,13 +1085,11 @@ def append_string_condition(string, bind_value, model, operator)
       end
     end
 
-    # TODO: document
     # @api private
     def append_operator_conditions(operator, bind_value, model)
       append_condition(operator.target, bind_value, model, operator.operator)
     end
 
-    # TODO: document
     # @api private
     def append_path(path, bind_value, model, operator)
       path.relationships.each do |relationship|
@@ -1146,7 +1141,6 @@ def extract_slice_arguments(*args)
       raise ArgumentError, "arguments may be 1 or 2 Integers, or 1 Range object, was: #{args.inspect}"
     end
 
-    # TODO: document
     # @api private
     def get_relative_position(offset, limit)
       new_offset = self.offset + offset
@@ -1169,7 +1163,6 @@ def record_value(record, property)
       end
     end
 
-    # TODO: document
     # @api private
     def each_comparison
       operands = conditions.operands.to_a
diff --git a/lib/dm-core/query/conditions/operation.rb b/lib/dm-core/query/conditions/operation.rb
index 8c1bf6acb..2ade12679 100644
--- a/lib/dm-core/query/conditions/operation.rb
+++ b/lib/dm-core/query/conditions/operation.rb
@@ -4,7 +4,6 @@ module Conditions
       class InvalidOperation < ArgumentError; end
 
       class Operation
-        # TODO: document
         # @api semipublic
         def self.new(slug, *operands)
           if klass = operation_class(slug)
@@ -14,13 +13,11 @@ def self.new(slug, *operands)
           end
         end
 
-        # TODO: document
         # @api semipublic
         def self.operation_class(slug)
           operation_classes[slug] ||= AbstractOperation.descendants.detect { |operation_class| operation_class.slug == slug }
         end
 
-        # TODO: document
         # @api private
         def self.slugs
           @slugs ||= AbstractOperation.descendants.map { |operation_class| operation_class.slug }
@@ -29,7 +26,6 @@ def self.slugs
         class << self
           private
 
-          # TODO: document
           # @api private
           def operation_classes
             @operation_classes ||= {}
@@ -44,23 +40,19 @@ class AbstractOperation
 
         equalize :slug, :sorted_operands
 
-        # TODO: document
         # @api semipublic
         attr_reader :operands
 
-        # TODO: document
         # @api private
         def self.descendants
           @descendants ||= Set.new
         end
 
-        # TODO: document
         # @api private
         def self.inherited(operation_class)
           descendants << operation_class
         end
 
-        # TODO: document
         # @api semipublic
         def self.slug(slug = nil)
           slug ? @slug = slug : @slug
@@ -76,14 +68,12 @@ def slug
           self.class.slug
         end
 
-        # TODO: document
         # @api semipublic
         def each
           @operands.each { |*block_args| yield(*block_args) }
           self
         end
 
-        # TODO: document
         # @api semipublic
         def valid?
           @operands.any? && @operands.all? do |operand|
@@ -95,7 +85,6 @@ def valid?
           end
         end
 
-        # TODO: document
         # @api semipublic
         def <<(operand)
           assert_valid_operand(operand)
@@ -103,7 +92,6 @@ def <<(operand)
           self
         end
 
-        # TODO: document
         # @api semipublic
         def merge(operands)
           operands.each { |operand| assert_valid_operand(operand) }
@@ -111,20 +99,17 @@ def merge(operands)
           self
         end
 
-        # TODO: document
         # @api semipublic
         def clear
           @operands.clear
           self
         end
 
-        # TODO: document
         # @api semipublic
         def inspect
           "#<#{self.class} @operands=#{@operands.inspect}>"
         end
 
-        # TODO: document
         # @api semipublic
         def to_s
           "(#{@operands.to_a.join(" #{slug.to_s.upcase} ")})"
@@ -142,19 +127,16 @@ def sorted_operands
 
         private
 
-        # TODO: document
         # @api semipublic
         def initialize(*operands)
           @operands = operands.to_set
         end
 
-        # TODO: document
         # @api semipublic
         def initialize_copy(*)
           @operands = @operands.map { |operand| operand.dup }.to_set
         end
 
-        # TODO: document
         # @api private
         def assert_valid_operand(operand)
           assert_kind_of 'operand', operand, Conditions::AbstractOperation, Conditions::AbstractComparison, Array
@@ -162,7 +144,6 @@ def assert_valid_operand(operand)
       end # class AbstractOperation
 
       module FlattenOperation
-        # TODO: document
         # @api semipublic
         def <<(operand)
           if operand.kind_of?(self.class)
@@ -178,7 +159,6 @@ class AndOperation < AbstractOperation
 
         slug :and
 
-        # TODO: document
         # @api semipublic
         def matches?(record)
           @operands.all? { |operand| operand.matches?(record) }
@@ -190,7 +170,6 @@ class OrOperation < AbstractOperation
 
         slug :or
 
-        # TODO: document
         # @api semipublic
         def matches?(record)
           @operands.any? { |operand| operand.matches?(record) }
@@ -200,20 +179,17 @@ def matches?(record)
       class NotOperation < AbstractOperation
         slug :not
 
-        # TODO: document
         # @api semipublic
         def matches?(record)
           not operand.matches?(record)
         end
 
-        # TODO: document
         # @api semipublic
         def <<(*)
           assert_one_operand
           super
         end
 
-        # TODO: document
         # @api semipublic
         def merge(operands)
           assert_one_operand
@@ -221,7 +197,6 @@ def merge(operands)
           super
         end
 
-        # TODO: document
         # @api semipublic
         def operand
           @operands.to_a.first
@@ -229,14 +204,12 @@ def operand
 
         private
 
-        # TODO: document
         # @api semipublic
         def initialize(*operands)
           assert_unary_operator(operands)
           super
         end
 
-        # TODO: document
         # @api private
         def assert_unary_operator(operands)
           if operands.size > 1
@@ -244,7 +217,6 @@ def assert_unary_operator(operands)
           end
         end
 
-        # TODO: document
         # @api private
         def assert_one_operand
           if operand
diff --git a/lib/dm-core/query/direction.rb b/lib/dm-core/query/direction.rb
index a93cee27b..9b969d37b 100644
--- a/lib/dm-core/query/direction.rb
+++ b/lib/dm-core/query/direction.rb
@@ -18,14 +18,12 @@ class Direction < Operator
       deprecate :property,  :target
       deprecate :direction, :operator
 
-      # TODO: document
       # @api private
       def reverse!
         @operator = @operator == :asc ? :desc : :asc
         self
       end
 
-      # TODO: document
       # @api private
       def get(resource)
         Sort.new(target.get(resource), @operator == :asc)
@@ -33,7 +31,6 @@ def get(resource)
 
       private
 
-      # TODO: document
       # @api private
       def initialize(target, operator = :asc)
         super
diff --git a/lib/dm-core/query/operator.rb b/lib/dm-core/query/operator.rb
index 381c428ff..d4e91a302 100644
--- a/lib/dm-core/query/operator.rb
+++ b/lib/dm-core/query/operator.rb
@@ -13,15 +13,12 @@ class Operator
 
       equalize :target, :operator
 
-      # TODO: document
       # @api private
       attr_reader :target
 
-      # TODO: document
       # @api private
       attr_reader :operator
 
-      # TODO: document
       # @api private
       def inspect
         "#<#{self.class.name} @target=#{target.inspect} @operator=#{operator.inspect}>"
@@ -29,7 +26,6 @@ def inspect
 
       private
 
-      # TODO: document
       # @api private
       def initialize(target, operator)
         assert_kind_of 'operator', operator, Symbol
diff --git a/lib/dm-core/query/path.rb b/lib/dm-core/query/path.rb
index 7e83a28b8..f8591eb2f 100644
--- a/lib/dm-core/query/path.rb
+++ b/lib/dm-core/query/path.rb
@@ -14,19 +14,15 @@ class Path
 
       equalize :relationships, :property
 
-      # TODO: document
       # @api semipublic
       attr_reader :repository_name
 
-      # TODO: document
       # @api semipublic
       attr_reader :relationships
 
-      # TODO: document
       # @api semipublic
       attr_reader :model
 
-      # TODO: document
       # @api semipublic
       attr_reader :property
 
@@ -39,19 +35,16 @@ def #{slug}
         RUBY
       end
 
-      # TODO: document
       # @api public
       def kind_of?(klass)
         super || (defined?(@property) ? @property.kind_of?(klass) : false)
       end
 
-      # TODO: document
       # @api public
       def instance_of?(klass)
         super || (defined?(@property) ? @property.instance_of?(klass) : false)
       end
 
-      # TODO: document
       # @api semipublic
       def respond_to?(method, include_private = false)
         super                                                                   ||
@@ -62,7 +55,6 @@ def respond_to?(method, include_private = false)
 
       private
 
-      # TODO: document
       # @api semipublic
       def initialize(relationships, property_name = nil)
         assert_kind_of 'relationships', relationships, Array
@@ -80,7 +72,6 @@ def initialize(relationships, property_name = nil)
         end
       end
 
-      # TODO: document
       # @api semipublic
       def method_missing(method, *args)
         if @property
diff --git a/lib/dm-core/query/sort.rb b/lib/dm-core/query/sort.rb
index bede3cede..4d2a5ebe8 100644
--- a/lib/dm-core/query/sort.rb
+++ b/lib/dm-core/query/sort.rb
@@ -3,17 +3,14 @@
 module DataMapper
   class Query
     class Sort
-      # TODO: document
       # @api semipublic
       attr_reader :value
 
-      # TODO: document
       # @api semipublic
       def direction
         @ascending ? :ascending : :descending
       end
 
-      # TODO: document
       # @api private
       def <=>(other)
         other_value = other.value
@@ -34,7 +31,6 @@ def <=>(other)
 
       private
 
-      # TODO: document
       # @api private
       def initialize(value, ascending = true)
         @value     = value
diff --git a/lib/dm-core/repository.rb b/lib/dm-core/repository.rb
index 6b676df93..834dbe0fc 100755
--- a/lib/dm-core/repository.rb
+++ b/lib/dm-core/repository.rb
@@ -42,7 +42,6 @@ def self.default_name
       :default
     end
 
-    # TODO: document
     # @api semipublic
     attr_reader :name
 
diff --git a/lib/dm-core/resource.rb b/lib/dm-core/resource.rb
index c6956edd8..1c8d46407 100644
--- a/lib/dm-core/resource.rb
+++ b/lib/dm-core/resource.rb
@@ -56,7 +56,6 @@ def self.included(model)
     # @api private
     attr_writer :collection
 
-    # TODO: document
     # @api public
     alias_method :model, :class
 
@@ -798,7 +797,6 @@ def collection_for_self
       Collection.new(query, [ self ])
     end
 
-    # TODO: document
     # @api private
     def parent_relationships
       parent_relationships = []
@@ -838,13 +836,11 @@ def child_relationships
       many_to_many + other
     end
 
-    # TODO: document
     # @api private
     def parent_resources
       parent_relationships.map { |relationship| relationship.get!(self) }
     end
 
-    # TODO: document
     # @api private
     def child_collections
       child_relationships.map { |relationship| relationship.get!(self) }
diff --git a/lib/dm-core/support/chainable.rb b/lib/dm-core/support/chainable.rb
index b5e760821..c7f402efb 100644
--- a/lib/dm-core/support/chainable.rb
+++ b/lib/dm-core/support/chainable.rb
@@ -1,7 +1,6 @@
 module DataMapper
   module Chainable
 
-    # TODO: document
     # @api private
     def chainable(&block)
       mod = Module.new(&block)
@@ -9,7 +8,6 @@ def chainable(&block)
       mod
     end
 
-    # TODO: document
     # @api private
     def extendable(&block)
       mod = Module.new(&block)
diff --git a/lib/dm-core/transaction.rb b/lib/dm-core/transaction.rb
index b6309ef59..279859743 100644
--- a/lib/dm-core/transaction.rb
+++ b/lib/dm-core/transaction.rb
@@ -172,7 +172,6 @@ def within
       end
     end
 
-    # TODO: document
     # @api private
     def method_missing(meth, *args, &block)
       if args.size == 1 && args.first.kind_of?(Adapters::AbstractAdapter)
@@ -200,7 +199,6 @@ def method_missing(meth, *args, &block)
       end
     end
 
-    # TODO: document
     # @api private
     def primitive_for(adapter)
       unless @adapters.include?(adapter)
@@ -216,7 +214,6 @@ def primitive_for(adapter)
 
     private
 
-    # TODO: document
     # @api private
     def validate_primitive(primitive)
       [:close, :begin, :rollback, :commit].each do |meth|
@@ -228,7 +225,6 @@ def validate_primitive(primitive)
       primitive
     end
 
-    # TODO: document
     # @api private
     def each_adapter(method, on_fail)
       begin
@@ -249,7 +245,6 @@ def each_adapter(method, on_fail)
       end
     end
 
-    # TODO: document
     # @api private
     def state_for(adapter)
       unless @adapters.include?(adapter)
@@ -259,7 +254,6 @@ def state_for(adapter)
       @adapters[adapter]
     end
 
-    # TODO: document
     # @api private
     def do_adapter(adapter, what, prerequisite)
       unless @transaction_primitives.include?(adapter)
@@ -275,13 +269,11 @@ def do_adapter(adapter, what, prerequisite)
       @adapters[adapter] = what
     end
 
-    # TODO: document
     # @api private
     def log_fatal_transaction_breakage(adapter)
       DataMapper.logger.fatal("#{self} experienced a totally broken transaction execution. Presenting member #{adapter.inspect}.")
     end
 
-    # TODO: document
     # @api private
     def connect_adapter(adapter)
       if @transaction_primitives.key?(adapter)
@@ -291,7 +283,6 @@ def connect_adapter(adapter)
       @transaction_primitives[adapter] = validate_primitive(adapter.transaction_primitive)
     end
 
-    # TODO: document
     # @api private
     def close_adapter_if_open(adapter)
       if @transaction_primitives.include?(adapter)
@@ -299,7 +290,6 @@ def close_adapter_if_open(adapter)
       end
     end
 
-    # TODO: document
     # @api private
     def close_adapter(adapter)
       unless @transaction_primitives.include?(adapter)
@@ -310,25 +300,21 @@ def close_adapter(adapter)
       @transaction_primitives.delete(adapter)
     end
 
-    # TODO: document
     # @api private
     def begin_adapter(adapter)
       do_adapter(adapter, :begin, :none)
     end
 
-    # TODO: document
     # @api private
     def commit_adapter(adapter)
       do_adapter(adapter, :commit, :begin)
     end
 
-    # TODO: document
     # @api private
     def rollback_adapter(adapter)
       do_adapter(adapter, :rollback, :begin)
     end
 
-    # TODO: document
     # @api private
     def rollback_and_close_adapter(adapter)
       rollback_adapter(adapter)
@@ -338,7 +324,6 @@ def rollback_and_close_adapter(adapter)
     module Adapter
       extend Chainable
 
-      # TODO: document
       # @api private
       def self.included(base)
         [ :Repository, :Model, :Resource ].each do |name|
@@ -402,13 +387,11 @@ def current_transaction
       chainable do
         protected
 
-        # TODO: document
         # @api semipublic
         def open_connection
           current_connection || super
         end
 
-        # TODO: document
         # @api semipublic
         def close_connection(connection)
           unless current_connection == connection
@@ -419,7 +402,6 @@ def close_connection(connection)
 
       private
 
-      # TODO: document
       # @api private
       def transactions
         Thread.current[:dm_transactions] ||= []
@@ -456,7 +438,6 @@ def transaction
     end # module Repository
 
     module Model
-      # TODO: document
       # @api private
       def self.included(mod)
         mod.descendants.each { |model| model.extend self }
@@ -493,7 +474,6 @@ def transaction
   module Adapters
     extendable do
 
-      # TODO: document
       # @api private
       def const_added(const_name)
         if Transaction.const_defined?(const_name)
diff --git a/lib/dm-core/type.rb b/lib/dm-core/type.rb
index 7d309e7ab..990dab5be 100755
--- a/lib/dm-core/type.rb
+++ b/lib/dm-core/type.rb
@@ -96,7 +96,6 @@ class Type
     ]
 
     class << self
-      # TODO: document
       # @api private
       def configure(primitive_type, options)
         warn "DataMapper.Type.configure is deprecated, specify the primitive and options explicitly (#{caller[0]})"
diff --git a/lib/dm-core/types/discriminator.rb b/lib/dm-core/types/discriminator.rb
index 813ce5b77..f409ccac2 100644
--- a/lib/dm-core/types/discriminator.rb
+++ b/lib/dm-core/types/discriminator.rb
@@ -5,7 +5,6 @@ class Discriminator < Type
       default   lambda { |resource, property| resource.model }
       nullable  false
 
-      # TODO: document
       # @api private
       def self.bind(property)
         repository_name = property.repository_name
diff --git a/lib/dm-core/types/object.rb b/lib/dm-core/types/object.rb
index d5b2bd2db..903a9f1a0 100644
--- a/lib/dm-core/types/object.rb
+++ b/lib/dm-core/types/object.rb
@@ -3,19 +3,16 @@ module Types
     class Object < Type
       primitive Text
 
-      # TODO: document
       # @api private
       def self.typecast(value, property)
         value
       end
 
-      # TODO: document
       # @api private
       def self.dump(value, property)
         [ Marshal.dump(value) ].pack('m')
       end
 
-      # TODO: document
       # @api private
       def self.load(value, property)
         Marshal.load(value.unpack('m').first) unless value.nil?
diff --git a/lib/dm-core/types/paranoid_boolean.rb b/lib/dm-core/types/paranoid_boolean.rb
index 98d006455..1cbf7f747 100644
--- a/lib/dm-core/types/paranoid_boolean.rb
+++ b/lib/dm-core/types/paranoid_boolean.rb
@@ -5,7 +5,6 @@ class ParanoidBoolean < Type
       default   false
       lazy      true
 
-      # TODO: document
       # @api private
       def self.bind(property)
         repository_name = property.repository_name
diff --git a/lib/dm-core/types/paranoid_datetime.rb b/lib/dm-core/types/paranoid_datetime.rb
index 58c177186..15a3aff2b 100644
--- a/lib/dm-core/types/paranoid_datetime.rb
+++ b/lib/dm-core/types/paranoid_datetime.rb
@@ -4,7 +4,6 @@ class ParanoidDateTime < Type
       primitive DateTime
       lazy      true
 
-      # TODO: document
       # @api private
       def self.bind(property)
         repository_name = property.repository_name