Merge pull request #123 from dogmatiq/79-clarify-new-semantics

Recommend returning the same value/type from each call to `New()`.

aggregate.go

@@ -18,9 +18,11 @@ package dogma
 // A command message can cause the creation or destruction of its target
 // instance.
 type AggregateMessageHandler interface {
-	// New constructs a new aggregate instance and returns its root.
+	// New constructs a new aggregate instance initialized with any
+	// default values and returns the aggregate root.
 	//
-	// The return value MUST NOT be nil.
+	// Repeated calls SHOULD return a value that is of the same type and
+	// initialized in the same way. The return value MUST NOT be nil.
 	New() AggregateRoot
 
 	// Configure produces a configuration for this handler by calling methods on

process.go

@@ -27,9 +27,11 @@ import (
 // updating a database or invoking an API operation that causes a state change.
 // Any such state changes should be communicated via a command message instead.
 type ProcessMessageHandler interface {
-	// New constructs a new process instance and returns its root.
+	// New constructs a new process instance initialized with any
+	// default values and returns the process root.
 	//
-	// The return value MUST NOT be nil.
+	// Repeated calls SHOULD return a value that is of the same type and
+	// initialized in the same way. The return value MUST NOT be nil.
 	New() ProcessRoot
 
 	// Configure produces a configuration for this handler by calling methods on