Document application-owned alias contracts

app.go

@@ -33,12 +33,18 @@ type commandNode struct {
 	command Command
 }
 
-// New creates an application with the supplied identity and initial
-// declarations.
+// New creates an application with the supplied identity and initial canonical
+// commands and routing rules. Use []Declaration to expand a mixed declaration
+// collection; []Command cannot be expanded as ...Declaration without
+// converting its elements.
+//
 // The identity name must not be empty. New installs its generated help and
-// version commands and caller declarations as one batch; an invalid declaration
-// returns an error without exposing an App. The root help and version names are
-// reserved for generated commands.
+// version commands and caller declarations as one batch; an invalid, nil, or
+// zero declaration returns an error without exposing an App. Factory issues
+// retained in Command and RoutingRule values are reported during installation.
+// Identical duplicate routing mappings are accepted; conflicting mappings
+// fail the batch. The root help and version names are reserved for generated
+// commands.
 func New(identity Identity, declarations ...Declaration) (*App, error) {
 	if identity.Name == "" {
 		return nil, fmt.Errorf("application identity name must not be empty")