fix bucket.Create method description (#201)

* fix bucket.Create method

Escrow `Bucket.Create` method and documentation is updated to be acurate.

fix #170

* replace escrow.Bucket.Create with Build method

Rename `Create` to `Build` and update documentation.

Create method should persist returned object in the store. Because of
how escrow extension is implemented, a zero value escrow instance cannot
be persisted due to validation.
Escrow controller is expecting a zero amount escrow instance, that it
will deposit initial amount to. Rename `Create` to `Build` so that the
logic can remain as is, but the confusing naming is fixed.

x/escrow/handler.go

@@ -88,11 +88,7 @@ func (h CreateEscrowHandler) Deliver(ctx weave.Context, db weave.KVStore,
 		Timeout:   msg.Timeout,
 		Memo:      msg.Memo,
 	}
-	obj, err := h.bucket.Create(db, escrow)
-	if err != nil {
-		return res, err
-	}
-
+	obj := h.bucket.Build(db, escrow)
 	if err := h.ops.Deposit(db, escrow, obj.Key(), sender, msg.Amount); err != nil {
 		return res, err
 	}

x/escrow/handler_test.go

@@ -6,16 +6,15 @@ import (
 	"fmt"
 	"testing"
 
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
-
 	"github.com/iov-one/weave"
 	"github.com/iov-one/weave/app"
 	"github.com/iov-one/weave/orm"
 	"github.com/iov-one/weave/store"
 	"github.com/iov-one/weave/x"
 	"github.com/iov-one/weave/x/cash"
 	"github.com/iov-one/weave/x/hashlock"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 )
 
 const Timeout = 12345

x/escrow/model.go

@@ -158,13 +158,11 @@ func idxArbiter(obj orm.Object) ([]byte, error) {
 	return esc.Arbiter, nil
 }
 
-// Create will calculate the next sequence number and then
-// store the escrow there.
-// Saves the object and returns it (to inspect the ID)
-func (b Bucket) Create(db weave.KVStore, escrow *Escrow) (orm.Object, error) {
+// Build assigns an ID to given escrow instance and returns it as an orm
+// Object. It does not persist the escrow in the store.
+func (b Bucket) Build(db weave.KVStore, escrow *Escrow) orm.Object {
 	key := b.idSeq.NextVal(db)
-	obj := orm.NewSimpleObj(key, escrow)
-	return obj, nil
+	return orm.NewSimpleObj(key, escrow)
 }
 
 // Save enforces the proper type