verror vdl generated Errorf<ErrorType> functions have confusing comments/argument names

[cosnicolaou]

A vdl error definition of the form:

error (
	Internal() {}
)

leads to generated code of the form:

// ErrorfInternal calls ErrInternal.Errorf with the supplied arguments.
func ErrorfInternal(ctx *context.T, format string) error {
	return ErrInternal.Errorf(ctx, format)
}

// MessageInternal calls ErrInternal.Message with the supplied arguments.
func MessageInternal(ctx *context.T, message string) error {
	return ErrInternal.Message(ctx, message)
}

// ParamsErrInternal extracts the expected parameters from the error's ParameterList.
func ParamsErrInternal(argumentError error) (verrorComponent string, verrorOperation string, returnErr error) {
	params := Params(argumentError)
	if params == nil {
		returnErr = fmt.Errorf("no parameters found in: %T: %v", argumentError, argumentError)
		return
	}
	iter := &paramListIterator{params: params, max: len(params)}

	if verrorComponent, verrorOperation, returnErr = iter.preamble(); returnErr != nil {
		return
	}

	return
}

The ErrorfInternal function looks like a mistake since there are no parameters beyond the format. This is because these functions are intended for encapsulating parameters within the verror implementation and for those parameters to be returned to the callee, even if that callee is remote. The confusion is that the Errorf method (ErrInternal.Errorf) performs this encapsulation, which for the vast, vast majority of cases, is never actually used. A better API would be separate parameter encapsulation from error message formatting. That is to provide two methods:

• Errorf - just generates an error, with normal, in-process error encapsulation as per go's error package.
• ErrorfWithParams - also encapsulates the parameters for transmission to remote processes.