Missing Documentation for instance#update

[rapito]

This is a duplicate of an open issue on the original repository:

Veraticus/Dynamoid#160

Also, I couldn't find any documentation where it explains the update usage on this gem. Even if we do need to pass a block, what is it for? It should be added to the documentation and/or readme of this repository.

For what I can see in the code, from the yield block you obtain an ItemUpdater which is part of the adapter plugin for aws-sdk-v2, at the very least the readme should relay the documentation back to the aws gem if needed with how to use it.

TL;DR

The following code crashes and there's no documentation about how to handle it or use the update method.

class Foo
	include Dynamoid::Document
	table name: :data_messages
	field :bar
end

Foo.first.update(bar: "this should be updated") -> Raises LocalJumpError: no block given (yield) and the record is not updated.

Foo.first.update(bar: "this should be updated") { |iu| puts "I'm a weird block" } -> No error but the record is not updated at all

So by digging into the codebase I found out the following is the actual way to update things (which is kind of unnatural), which makes the method a pain to use and figure out.

Foo.first.update { |iu| iu.set bar: "this should be updated" } -> No error and the record is finally updated

Also please note that this is executing the update method on the model instance and not the class.

[andrykonchin]

Yeah, definitely there is a lack of documentation in the project. Some aspects should be updated in Readme.md as well as in the Yard documentation.

Any PR with documentation is welcomed.

[andrykonchin]

Documentation was added here #431

dynamoid/lib/dynamoid/persistence.rb

Lines 594 to 641 in 555b0e7

	# Update a model.
	#
	# Runs validation and callbacks. Reloads all attribute values.
	#
	# Accepts mandatory block in order to specify operations which will modify
	# attributes. Supports following operations: +add+, +delete+ and +set+.
	#
	# Operation +add+ just adds a value for numeric attributes and join
	# collections if attribute is a collection (one of +array+, +set+ or
	# +map+).
	#
	# user.update do |t|
	# t.add(age: 1, followers_count: 5)
	# t.add(hobbies: ['skying', 'climbing'])
	# end
	#
	# Operation +delete+ is applied to collection attribute types and
	# substructs one collection from another.
	#
	# user.update do |t|
	# t.delete(hobbies: ['skying'])
	# end
	#
	# Operation +set+ just changes an attribute value:
	#
	# user.update do |t|
	# t.set(age: 21)
	# end
	#
	# All the operations works like +ADD+, +DELETE+ and +PUT+ actions supported
	# by +AttributeUpdates+
	# {parameter}[https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LegacyConditionalParameters.AttributeUpdates.html]
	# of +UpdateItem+ operation.
	#
	# Can update a model conditionaly:
	#
	# user.update(if: { age: 20 }) do |t|
	# t.add(age: 1)
	# end
	#
	# If a document doesn't meet conditions it just returns +false+. Otherwise it returns +true+.
	#
	# It will increment the +lock_version+ attribute if a table has the column,
	# but will not check it. Thus, a concurrent +save+ call will never cause an
	# +update!+ to fail, but an +update!+ may cause a concurrent +save+ to
	# fail.
	#
	# @param conditions [Hash] Conditions on model attributes to make a conditional update (optional)