dynamoid 3.5.0 → 3.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 16a6980d441040611894ad405ce797b6ef655e9e2730b010d72ff3e65771129f
-  data.tar.gz: 1ca556953abc411f0b7e2fd5e5c74518a7da4381b86449b2f49e81d9f76ee0a8
+  metadata.gz: 26990dd042447eeba355601d0c7eb3657bcc482e80d00c1da5602d2f82765504
+  data.tar.gz: 76e1778155fb8a7a1d3135d4886d9e7caf1a07b72263fc38d9162ae946d5dab1
 SHA512:
-  metadata.gz: 71856592a8a381b27517682c6ce7bb48047de11dc2fbb17c175af629d3ec7e2b63895e9b24c943b57a93e47db0b1de390454b5a89d71899a59c9208a79e0595e
-  data.tar.gz: 8cd759df57475c7566ef0ceae781d21eb443cb1dcd0f6da0f3eaa778fe6a3abeac8865a1198a2dbd2f435eec2cb5317b47ce5e5bd5b9dadbe7537a412053492b
+  metadata.gz: 2aadf93639577566ed5dd9dadff596316f3d22384f5d7dabd0e06aa49992d3a58e824a8c150002c3a39d6e42f7b2b17c4f383bda2c145f4d05e1d56bf21a5e54
+  data.tar.gz: 14801f95c8cd1a241d2b1522b05a1e7af307822cef50e4515502f641027ade16aaf750a099801a2f2e4e379b15a4cd96e78f84754278db37d2e6fcdaab57b242

data/CHANGELOG.md

@@ -1,18 +1,49 @@
 # HEAD
 
-## Breaking
+## Features
+
+## Improvements
+
+## Fixes
+
+
+---
+
+
+
+# 3.6.0 / 2020-07-13
+
 
 ## Features
 
+* [#458](https://github.com/Dynamoid/dynamoid/pull/458) Added `binary` field type
+* [#459](https://github.com/Dynamoid/dynamoid/pull/459) Added `log_formatter` config option and changed default logging format
+
 ## Improvements
 
+* [#423](https://github.com/Dynamoid/dynamoid/pull/423) Added warning when generated for a field methods override existing ones
+* [#429](https://github.com/Dynamoid/dynamoid/pull/429) Added `raise_error` option for `find` method
+* [#440](https://github.com/Dynamoid/dynamoid/pull/440) Optimized performance of `first` method when there are only conditions on key attribute in a query (@mrkamel)
+* [#445](https://github.com/Dynamoid/dynamoid/pull/445) Support `limit` parameter in `first` method (@mrkamel)
+* [#450](https://github.com/Dynamoid/dynamoid/pull/450) Got rid of `null-logger` gem to make Dynamoid dependencies license suitable for commercial use (@yakjuly)
+* [#454](https://github.com/Dynamoid/dynamoid/pull/454) Added block argument to `create`/`create!` methods
+* [#456](https://github.com/Dynamoid/dynamoid/pull/456) Detect when `find` method requires a range key argument and raise `Dynamoid::Errors::MissingRangeKey` exception if it's missing
+* YARD documentation:
+  * added missing documentation so now all the public methods are documented
+  * hid all the private methods and classes
+
 ## Fixes
 
+* [#425](https://github.com/Dynamoid/dynamoid/pull/425) Fixed typos in the README.md file (@omarsotillo)
+* [#432](https://github.com/Dynamoid/dynamoid/pull/432) Support tables that use "hash_key" as their partition key name (@remomueller)
+* [#434](https://github.com/Dynamoid/dynamoid/pull/434) Support tables that have attribute with name "range_value"
+* [#453](https://github.com/Dynamoid/dynamoid/pull/453) Fixed issue with using `type` attribute as a GSI hash key
+
 ---
 
 
 
-# 3.5 / 2020-04-04
+# 3.5.0 / 2020-04-04
 
 
 ## Features
@@ -20,13 +51,13 @@
 * Feature: [#408](https://github.com/Dynamoid/dynamoid/pull/408) Added `ActiveSupport` load hook on `Dynamoid` load (@aaronmallen)
 * Feature: [#422](https://github.com/Dynamoid/dynamoid/pull/422) Added `.pluck` method
 
-Fixes:
+## Fixes:
 * Fix: [#410](https://github.com/Dynamoid/dynamoid/pull/410) Fixed creating GSI when table uses on-demand capacity provisioning (@icy-arctic-fox)
 * Fix: [#414](https://github.com/Dynamoid/dynamoid/pull/414) Fixed lazy table creation
 * Fix: [#415](https://github.com/Dynamoid/dynamoid/pull/415) Fixed RubyDoc comment (@walkersumida)
 * Fix: [#420](https://github.com/Dynamoid/dynamoid/pull/420) Fixed `#persisted?` for deleted/destroyed models
 
-Improvements:
+## Improvements:
 * Improvement: [#416](https://github.com/Dynamoid/dynamoid/pull/416) Improved speed of Adapter's `truncate` method. It now uses `#batch_delete_item` method (@TheSmartnik)
 * Improvement: [#421](https://github.com/Dynamoid/dynamoid/pull/421) Added `touch: false` option of the #save method
 * Improvement: [#423](https://github.com/Dynamoid/dynamoid/pull/423) Added warning when generated for a field methods override existing ones

data/README.md

@@ -212,16 +212,17 @@ each field. Every field on the object must be included here; if you miss
 any they'll be completely bypassed during DynamoDB's initialization and
 will not appear on the model objects.
 
-By default, fields are assumed to be of type `:string`. Other built-in
-types are `:integer`, `:number`, `:set`, `:array`, `:map`, `:datetime`,
-`date`, `:boolean`, `:raw` and `:serialized`. `array` and `map` match
-List and Map DynamoDB types respectively. `raw` type means you can store
-Ruby Array, Hash, String and numbers. If built-in types do not suit you,
-you can use a custom field type represented by an arbitrary class,
-provided that the class supports a compatible serialization interface.
-The primary use case for using a custom field type is to represent your
-business logic with high-level types, while ensuring portability or
-backward-compatibility of the serialized representation.
+By default, fields are assumed to be of type `string`. Other built-in
+types are `integer`, `number`, `set`, `array`, `map`, `datetime`,
+`date`, `boolean`, `binary`, `raw` and `serialized`. `array` and
+`map` match List and Map DynamoDB types respectively. `raw` type means
+you can store Ruby Array, Hash, String and numbers. If built-in types do
+not suit you, you can use a custom field type represented by an
+arbitrary class, provided that the class supports a compatible
+serialization interface.  The primary use case for using a custom field
+type is to represent your business logic with high-level types, while
+ensuring portability or backward-compatibility of the serialized
+representation.
 
 #### Note on boolean type
 
@@ -232,7 +233,7 @@ easily achieve this with `store_as_native_boolean` field option:
 
 ```ruby
 class Document
-  include DynamoId::Document
+  include Dynamoid::Document
 
   field :active, :boolean, store_as_native_boolean: false
 end
@@ -246,7 +247,7 @@ strings instead then set `store_as_string` to `true`
 
 ```ruby
 class Document
-  include DynamoId::Document
+  include Dynamoid::Document
 
   field :sent_on, :date, store_as_string: true
 end
@@ -261,7 +262,7 @@ as ISO-8601 formatted strings instead then set `store_as_string` to
 
 ```ruby
 class Document
-  include DynamoId::Document
+  include Dynamoid::Document
 
   field :sent_at, :datetime, store_as_string: true
 end
@@ -293,7 +294,7 @@ types.
 
 ```ruby
 class Document
-  include DynamoId::Document
+  include Dynamoid::Document
 
   field :tags, :set, of: :integer
 end
@@ -305,7 +306,7 @@ elements type:
 
 ```ruby
 class Document
-  include DynamoId::Document
+  include Dynamoid::Document
 
   field :values, :set, of: { serialized: { serializer: JSON } }
   field :dates, :set, of: { date: { store_as_string: true } }
@@ -329,7 +330,7 @@ natively, you should specify element type with `of` option:
 
 ```ruby
 class Document
-  include DynamoId::Document
+  include Dynamoid::Document
 
   field :dates, :array, of: :date
 end
@@ -762,7 +763,7 @@ for requesting documents in batches:
 
 ```ruby
 # Do some maintenance on the entire table without flooding DynamoDB
-Address.all(batch_size: 100).each { |address| address.do_some_work; sleep(0.01) }
+Address.batch(100).each { |address| address.do_some_work; sleep(0.01) }
 Address.record_limit(10_000).batch(100).each { … } # Batch specified as part of a chain
 ```
 
@@ -1068,7 +1069,7 @@ Listed below are all configuration options.
 * `models_dir` - `dynamoid:create_tables` rake task loads DynamoDb
   models from this directory. Default is `./app/models`.
 * `application_timezone` - Dynamoid converts all `datetime` fields to
-* specified time zone when loads data from the storage.
+  specified time zone when loads data from the storage.
   Acceptable values - `:utc`, `:local` (to use system time zone) and
   time zone name e.g. `Eastern Time (US & Canada)`. Default is `utc`
 * `dynamodb_timezone` - When a datetime field is stored in string format
@@ -1088,6 +1089,11 @@ Listed below are all configuration options.
   `nil`
 * `backoff_strategies`: is a hash and contains all available strategies.
   Default is { constant: ..., exponential: ...}
+* `log_formatter`: overrides default AWS SDK formatter. There are
+  several canned formatters: `Aws::Log::Formatter.default`,
+  `Aws::Log::Formatter.colored` and `Aws::Log::Formatter.short`. Please
+  look into `Aws::Log::Formatter` AWS SDK documentation in order to
+  provide own formatter.
 * `http_continue_timeout`: The number of seconds to wait for a
   100-continue HTTP response before sending the request body. Default
   option value is `nil`. If not specified effected value is `1`

data/lib/dynamoid.rb

@@ -57,6 +57,7 @@ module Dynamoid
     @included_models ||= []
   end
 
+  # @private
   def adapter
     @adapter ||= Adapter.new
   end

data/lib/dynamoid/adapter.rb

@@ -11,6 +11,7 @@ module Dynamoid
   # 1) For the rest of Dynamoid, the gateway to DynamoDB.
   # 2) Allows switching `config.adapter` to ease development of a new adapter.
   # 3) Caches the list of tables Dynamoid knows about.
+  # @private
   class Adapter
     def initialize
       @adapter_ = Concurrent::Atom.new(nil)
@@ -78,8 +79,8 @@ module Dynamoid
     #
     # @param [String] table the name of the table to write the object to
     # @param [Array] ids to fetch, can also be a string of just one id
-    # @param [Hash] options: Passed to the underlying query. The :range_key option is required whenever the table has a range key,
-    #                        unless multiple ids are passed in.
+    # @param [Hash] options Passed to the underlying query. The :range_key option is required whenever the table has a range key,
+    #                       unless multiple ids are passed in.
     #
     # @since 0.2.0
     def read(table, ids, options = {}, &blk)
@@ -94,7 +95,9 @@ module Dynamoid
     #
     # @param [String] table the name of the table to write the object to
     # @param [Array] ids to delete, can also be a string of just one id
-    # @param [Hash] range_key of the record to delete, can also be a string of just one range_key
+    # @param [Hash] options allowed only +range_key+ - range key or array of
+    #                       range keys of the record to delete, can also be
+    #                       a string of just one range_key, and +conditions+
     #
     def delete(table, ids, options = {})
       range_key = options[:range_key] # array of range keys that matches the ids passed in
@@ -115,7 +118,7 @@ module Dynamoid
     # Scans a table. Generally quite slow; try to avoid using scan if at all possible.
     #
     # @param [String] table the name of the table to write the object to
-    # @param [Hash] scan_hash a hash of attributes: matching records will be returned by the scan
+    # @param [Hash] query a hash of attributes: matching records will be returned by the scan
     #
     # @since 0.2.0
     def scan(table, query = {}, opts = {})

data/lib/dynamoid/adapter_plugin/aws_sdk_v3.rb

@@ -9,6 +9,7 @@ require_relative 'aws_sdk_v3/table'
 require_relative 'aws_sdk_v3/until_past_table_status'
 
 module Dynamoid
+  # @private
   module AdapterPlugin
     # The AwsSdkV3 adapter provides support for the aws-sdk version 2 for ruby.
     class AwsSdkV3
@@ -64,8 +65,8 @@ module Dynamoid
       # Build an array of values for Condition
       # Is used in ScanFilter and QueryFilter
       # https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Condition.html
-      # @params [String] operator: value of RANGE_MAP or FIELD_MAP hash, e.g. "EQ", "LT" etc
-      # @params [Object] value: scalar value or array/set
+      # @param [String] operator value of RANGE_MAP or FIELD_MAP hash, e.g. "EQ", "LT" etc
+      # @param [Object] value scalar value or array/set
       def self.attribute_value_list(operator, value)
         # For BETWEEN and IN operators we should keep value as is (it should be already an array)
         # NULL and NOT_NULL require absence of attribute list
@@ -108,12 +109,14 @@ module Dynamoid
           end
         end
 
-        # https://github.com/aws/aws-sdk-ruby/blob/master/gems/aws-sdk-core/lib/aws-sdk-core/plugins/logging.rb
-        # https://github.com/aws/aws-sdk-ruby/blob/master/gems/aws-sdk-core/lib/aws-sdk-core/log/formatter.rb
-        formatter = Aws::Log::Formatter.new(':operation | Request :http_request_body | Response :http_response_body')
         @connection_hash[:logger] = Dynamoid::Config.logger
         @connection_hash[:log_level] = :debug
-        @connection_hash[:log_formatter] = formatter
+
+        # https://github.com/aws/aws-sdk-ruby/blob/master/gems/aws-sdk-core/lib/aws-sdk-core/plugins/logging.rb
+        # https://github.com/aws/aws-sdk-ruby/blob/master/gems/aws-sdk-core/lib/aws-sdk-core/log/formatter.rb
+        if Dynamoid::Config.log_formatter
+          @connection_hash[:log_formatter] = Dynamoid::Config.log_formatter
+        end
 
         @connection_hash
       end
@@ -141,9 +144,9 @@ module Dynamoid
       #   end
       #
       # @param [String] table_name the name of the table
-      # @param [Array]  items to be processed
-      # @param [Hash]   additional options
-      # @param [Proc]   optional block
+      # @param [Array]  objects to be processed
+      # @param [Hash]   options additional options
+      # @yield [true|false] invokes an optional block with argument - whether there are unprocessed items
       #
       # See:
       # * http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_BatchWriteItem.html
@@ -198,9 +201,9 @@ module Dynamoid
       #     end
       #   end
       #
-      # @param [Hash] table_ids the hash of tables and IDs to retrieve
+      # @param [Hash] table_names_with_ids the hash of tables and IDs to retrieve
       # @param [Hash] options to be passed to underlying BatchGet call
-      # @param [Proc] optional block can be passed to handle each batch of items
+      # @param [Proc] block optional block can be passed to handle each batch of items
       #
       # @return [Hash] a hash where keys are the table names and the values are the retrieved items
       #

data/lib/dynamoid/adapter_plugin/aws_sdk_v3/batch_get_item.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Dynamoid
+  # @private
   module AdapterPlugin
     class AwsSdkV3
       # Documentation

data/lib/dynamoid/adapter_plugin/aws_sdk_v3/create_table.rb

@@ -3,6 +3,7 @@
 require_relative 'until_past_table_status'
 
 module Dynamoid
+  # @private
   module AdapterPlugin
     class AwsSdkV3
       class CreateTable
@@ -87,9 +88,9 @@ module Dynamoid
         # Builds aws attributes definitions based off of primary hash/range and
         # secondary indexes
         #
-        # @param key_data
-        # @option key_data [Hash] hash_key_schema - eg: {:id => :string}
-        # @option key_data [Hash] range_key_schema - eg: {:created_at => :number}
+        # @param key_schema
+        # @option key_schema [Hash] hash_key_schema - eg: {:id => :string}
+        # @option key_schema [Hash] range_key_schema - eg: {:created_at => :number}
         # @param [Hash] secondary_indexes
         # @option secondary_indexes [Array<Dynamoid::Indexes::Index>] :local_secondary_indexes
         # @option secondary_indexes [Array<Dynamoid::Indexes::Index>] :global_secondary_indexes
@@ -130,8 +131,8 @@ module Dynamoid
         end
 
         # Builds an attribute definitions based on hash key and range key
-        # @params [Hash] hash_key_schema - eg: {:id => :string}
-        # @params [Hash] range_key_schema - eg: {:created_at => :datetime}
+        # @param [Hash] hash_key_schema - eg: {:id => :string}
+        # @param [Hash] range_key_schema - eg: {:created_at => :datetime}
         # @return [Array]
         def build_attribute_definitions(hash_key_schema, range_key_schema = nil)
           attrs = []
@@ -152,8 +153,8 @@ module Dynamoid
         end
 
         # Builds an aws attribute definition based on name and dynamoid type
-        # @params [Symbol] name - eg: :id
-        # @params [Symbol] dynamoid_type - eg: :string
+        # @param [Symbol] name - eg: :id
+        # @param [Symbol] dynamoid_type - eg: :string
         # @return [Hash]
         def attribute_definition_element(name, dynamoid_type)
           aws_type = api_type(dynamoid_type)

data/lib/dynamoid/adapter_plugin/aws_sdk_v3/item_updater.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Dynamoid
+  # @private
   module AdapterPlugin
     class AwsSdkV3
       # Mimics behavior of the yielded object on DynamoDB's update_item API (high level).
@@ -20,8 +21,8 @@ module Dynamoid
         # Adds the given values to the values already stored in the corresponding columns.
         # The column must contain a Set or a number.
         #
-        # @param [Hash] vals keys of the hash are the columns to update, vals are the values to
-        #               add. values must be a Set, Array, or Numeric
+        # @param [Hash] values keys of the hash are the columns to update, values
+        #                      are the values to add. values must be a Set, Array, or Numeric
         #
         def add(values)
           @additions.merge!(sanitize_attributes(values))

data/lib/dynamoid/adapter_plugin/aws_sdk_v3/middleware/backoff.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Dynamoid
+  # @private
   module AdapterPlugin
     class AwsSdkV3
       module Middleware

data/lib/dynamoid/adapter_plugin/aws_sdk_v3/middleware/limit.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Dynamoid
+  # @private
   module AdapterPlugin
     class AwsSdkV3
       module Middleware

data/lib/dynamoid/adapter_plugin/aws_sdk_v3/middleware/start_key.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Dynamoid
+  # @private
   module AdapterPlugin
     class AwsSdkV3
       module Middleware

data/lib/dynamoid/adapter_plugin/aws_sdk_v3/query.rb

@@ -5,6 +5,7 @@ require_relative 'middleware/limit'
 require_relative 'middleware/start_key'
 
 module Dynamoid
+  # @private
   module AdapterPlugin
     class AwsSdkV3
       class Query

data/lib/dynamoid/adapter_plugin/aws_sdk_v3/scan.rb

@@ -5,6 +5,7 @@ require_relative 'middleware/limit'
 require_relative 'middleware/start_key'
 
 module Dynamoid
+  # @private
   module AdapterPlugin
     class AwsSdkV3
       class Scan

data/lib/dynamoid/adapter_plugin/aws_sdk_v3/table.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Dynamoid
+  # @private
   module AdapterPlugin
     class AwsSdkV3
       # Represents a table. Exposes data from the "DescribeTable" API call, and also

data/lib/dynamoid/adapter_plugin/aws_sdk_v3/until_past_table_status.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Dynamoid
+  # @private
   module AdapterPlugin
     class AwsSdkV3
       class UntilPastTableStatus

data/lib/dynamoid/application_time_zone.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Dynamoid
+  # @private
   module ApplicationTimeZone
     def self.at(value)
       case Dynamoid::Config.application_timezone

data/lib/dynamoid/associations.rb

@@ -25,12 +25,55 @@ module Dynamoid
     end
 
     module ClassMethods
-      # create a has_many association for this document.
+      # Declare a +has_many+ association for this document.
       #
-      # @param [Symbol] name the name of the association
-      # @param [Hash] options options to pass to the association constructor
+      #   class Category
+      #     include Dynamoid::Document
+      #
+      #     has_many :posts
+      #   end
+      #
+      # Association is an enumerable collection and supports following addition
+      # operations:
+      #
+      # * +create+
+      # * +create!+
+      # * +destroy_all+
+      # * +delete_all+
+      # * +delete+
+      # * +<<+
+      # * +where+
+      # * +all+
+      # * +empty?+
+      # * +size+
+      #
+      # When a name of an associated class doesn't match an association name a
+      # class name should be specified explicitly either with +class+ or
+      # +class_name+ option:
+      #
+      #   has_many :labels, class: Tag
+      #   has_many :labels, class_name: 'Tag'
+      #
+      # When associated class has own +belongs_to+ association to
+      # the current class and the name doesn't match a name of the current
+      # class this name can be specified with +inverse_of+ option:
+      #
+      #   class Post
+      #     include Dynamoid::Document
+      #
+      #     belongs_to :item, class_name: 'Tag'
+      #   end
+      #
+      #   class Tag
+      #     include Dynamoid::Document
+      #
+      #     has_many :posts, inverse_of: :item
+      #   end
+      #
+      # @param name [Symbol] the name of the association
+      # @param options [Hash] options to pass to the association constructor
       # @option options [Class] :class the target class of the has_many association; that is, the belongs_to class
-      # @option options [Symbol] :class_name the name of the target class of the association; that is, the name of the belongs_to class
+      # @option options [String] :class_name the name of the target class of the association; that is, the name of the belongs_to class
       # @option options [Symbol] :inverse_of the name of the association on the target class; that is, if the class has a belongs_to association, the name of that association
       #
       # @since 0.2.0
@@ -38,12 +81,47 @@ module Dynamoid
         association(:has_many, name, options)
       end
 
-      # create a has_one association for this document.
+      # Declare a +has_one+ association for this document.
+      #
+      #   class Image
+      #     include Dynamoid::Document
       #
-      # @param [Symbol] name the name of the association
-      # @param [Hash] options options to pass to the association constructor
+      #     has_one :post
+      #   end
+      #
+      # Association supports following operations:
+      #
+      # * +create+
+      # * +create!+
+      # * +delete+
+      #
+      # When a name of an associated class doesn't match an association name a
+      # class name should be specified explicitly either with +class+ or
+      # +class_name+ option:
+      #
+      #   has_one :item, class: Post
+      #   has_one :item, class_name: 'Post'
+      #
+      # When associated class has own +belong_to+ association to the current
+      # class and the name doesn't match a name of the current class this name
+      # can be specified with +inverse_of+ option:
+      #
+      #   class Post
+      #     include Dynamoid::Document
+      #
+      #     belongs_to :logo, class_name: 'Image'
+      #   end
+      #
+      #   class Image
+      #     include Dynamoid::Document
+      #
+      #     has_one :post, inverse_of: :logo
+      #   end
+      #
+      # @param name [Symbol] the name of the association
+      # @param options [Hash] options to pass to the association constructor
       # @option options [Class] :class the target class of the has_one association; that is, the belongs_to class
-      # @option options [Symbol] :class_name the name of the target class of the association; that is, the name of the belongs_to class
+      # @option options [String] :class_name the name of the target class of the association; that is, the name of the belongs_to class
       # @option options [Symbol] :inverse_of the name of the association on the target class; that is, if the class has a belongs_to association, the name of that association
       #
       # @since 0.2.0
@@ -51,25 +129,110 @@ module Dynamoid
         association(:has_one, name, options)
       end
 
-      # create a belongs_to association for this document.
+      # Declare a +belongs_to+ association for this document.
+      #
+      #   class Post
+      #     include Dynamoid::Document
       #
-      # @param [Symbol] name the name of the association
-      # @param [Hash] options options to pass to the association constructor
+      #     belongs_to :categories
+      #   end
+      #
+      # Association supports following operations:
+      #
+      # * +create+
+      # * +create!+
+      # * +delete+
+      #
+      # When a name of an associated class doesn't match an association name a
+      # class name should be specified explicitly either with +class+ or
+      # +class_name+ option:
+      #
+      #   belongs_to :item, class: Post
+      #   belongs_to :item, class_name: 'Post'
+      #
+      # When associated class has own +has_many+ or +has_one+ association to
+      # the current class and the name doesn't match a name of the current
+      # class this name can be specified with +inverse_of+ option:
+      #
+      #   class Category
+      #     include Dynamoid::Document
+      #
+      #     has_many :items, class_name: 'Post'
+      #   end
+      #
+      #   class Post
+      #     include Dynamoid::Document
+      #
+      #     belongs_to :categories, inverse_of: :items
+      #   end
+      #
+      # By default a hash key attribute name is +id+. If an associated class
+      # uses another name for a hash key attribute it should be specified in
+      # the +belongs_to+ association:
+      #
+      #   belongs_to :categories, foreign_key: :uuid
+      #
+      # @param name [Symbol] the name of the association
+      # @param options [Hash] options to pass to the association constructor
       # @option options [Class] :class the target class of the has_one association; that is, the has_many or has_one class
-      # @option options [Symbol] :class_name the name of the target class of the association; that is, the name of the has_many or has_one class
+      # @option options [String] :class_name the name of the target class of the association; that is, the name of the has_many or has_one class
       # @option options [Symbol] :inverse_of the name of the association on the target class; that is, if the class has a has_many or has_one association, the name of that association
+      # @option options [Symbol] :foreign_key the name of a hash key attribute in the target class
       #
       # @since 0.2.0
       def belongs_to(name, options = {})
         association(:belongs_to, name, options)
       end
 
-      # create a has_and_belongs_to_many association for this document.
+      # Declare a +has_and_belongs_to_many+ association for this document.
+      #
+      #   class Post
+      #     include Dynamoid::Document
+      #
+      #     has_and_belongs_to_many :tags
+      #   end
+      #
+      # Association is an enumerable collection and supports following addition
+      # operations:
+      #
+      # * +create+
+      # * +create!+
+      # * +destroy_all+
+      # * +delete_all+
+      # * +delete+
+      # * +<<+
+      # * +where+
+      # * +all+
+      # * +empty?+
+      # * +size+
+      #
+      # When a name of an associated class doesn't match an association name a
+      # class name should be specified explicitly either with +class+ or
+      # +class_name+ option:
+      #
+      #   has_and_belongs_to_many :labels, class: Tag
+      #   has_and_belongs_to_many :labels, class_name: 'Tag'
+      #
+      # When associated class has own +has_and_belongs_to_many+ association to
+      # the current class and the name doesn't match a name of the current
+      # class this name can be specified with +inverse_of+ option:
+      #
+      #   class Tag
+      #     include Dynamoid::Document
+      #
+      #     has_and_belongs_to_many :items, class_name: 'Post'
+      #   end
+      #
+      #   class Post
+      #     include Dynamoid::Document
+      #
+      #     has_and_belongs_to_many :tags, inverse_of: :items
+      #   end
       #
-      # @param [Symbol] name the name of the association
-      # @param [Hash] options options to pass to the association constructor
+      # @param name [Symbol] the name of the association
+      # @param options [Hash] options to pass to the association constructor
       # @option options [Class] :class the target class of the has_and_belongs_to_many association; that is, the belongs_to class
-      # @option options [Symbol] :class_name the name of the target class of the association; that is, the name of the belongs_to class
+      # @option options [String] :class_name the name of the target class of the association; that is, the name of the belongs_to class
       # @option options [Symbol] :inverse_of the name of the association on the target class; that is, if the class has a belongs_to association, the name of that association
       #
       # @since 0.2.0
@@ -81,9 +244,9 @@ module Dynamoid
 
       # create getters and setters for an association.
       #
-      # @param [Symbol] symbol the type (:has_one, :has_many, :has_and_belongs_to_many, :belongs_to) of the association
-      # @param [Symbol] name the name of the association
-      # @param [Hash] options options to pass to the association constructor; see above for all valid options
+      # @param type [Symbol] the type (:has_one, :has_many, :has_and_belongs_to_many, :belongs_to) of the association
+      # @param name [Symbol] the name of the association
+      # @param options [Hash] options to pass to the association constructor; see above for all valid options
       #
       # @since 0.2.0
       def association(type, name, options = {})