handler: remove implementation details from docs (#96)

Fixes #95.

handler/handler.go

@@ -250,21 +250,10 @@ func (fi *FuncInfo) Wrap() Func {
 // If fn does not have one of these forms, Check reports an error.
 //
 // If the type of X is a struct or a pointer to a struct, the generated wrapper
-// accepts JSON parameters as either an object or an array.  The names used to
-// map array elements to struct fields are chosen by examining the fields of X
-// in order of their declaration.  Unexported fields are skipped, and the
-// parameter name for each exported field is chosen by following these rules,
-// in order:
-//
-// If the field has a `json:"-"` tag, the field is skipped.
-//
-// Otherwise, if the field has a `json:"name"` tag and the name is not empty,
-// "name" is used.
-//
-// Otherwise, if the field is anonymous (embedded) it is skipped. To include an
-// anonymous field, ensure it is tagged for one of the previous rules.
-//
-// Otherwise the name of the field is used as-written.
+// accepts JSON parameters as either an object or an array.  Array parameters
+// are mapped to the fields of X in the order of field declaration, save that
+// unexported fields are skipped. If a field has a `json:"-"` tag, it is also
+// skipped. Anonymous fields are skipped unless they are tagged.
 //
 // For other (non-struct) argument types, the accepted format is whatever the
 // json.Unmarshal function can decode into the value.  Note, however, that the

handler/positional.go

@@ -83,30 +83,31 @@ func structFieldNames(atype reflect.Type) (bool, []string) {
 // type whose fields correspond to the non-context arguments of fn.  The names
 // are used as the JSON field keys for the corresponding parameters.
 //
-// When converted into a handler.Func, the wrapped function accepts a JSON
-// object with the field keys named. For example, given:
+// When converted into a handler.Func, the wrapped function accepts either a
+// JSON array with exactly n members, or a JSON object with the field keys
+// named. For example, given:
 //
 //	func add(ctx context.Context, x, y int) int { return x + y }
 //
 //	fi, err := handler.Positional(add, "first", "second")
 //	// ...
 //	call := fi.Wrap()
 //
-// the resulting JSON-RPC handler accepts a parameter object like:
+// the resulting handler accepts a JSON array with with (exactly) the same
+// number of elements as the positional parameters:
 //
-//	{"first": 17, "second": 23}
-//
-// where "first" is mapped to argument x and "second" to argument y.  Unknown
-// field keys generate an error. The field names are not required to match the
-// parameter names declared by the function; it is the names assigned here that
-// determine which object keys are accepted.
+//	[17, 23]
 //
-// The wrapped function will also accept a JSON array with with (exactly) the
-// same number of elements as the positional parameters:
+// No arguments can be omitted in this format, but the caller can use a JSON
+// "null" in place of any argument.  The handler will also accept a parameter
+// object like:
 //
-//	[17, 23]
+//	{"first": 17, "second": 23}
 //
-// Unlike the object format, no arguments can be omitted in this format.
+// where "first" is mapped to argument x and "second" to argument y.  In this
+// form, fields may be omitted, but unknown field keys generate an error. The
+// object keys are taken from the arguments to Positional, not the parameter
+// names declared on the function.
 func Positional(fn any, names ...string) (*FuncInfo, error) {
 	if fn == nil {
 		return nil, errors.New("nil function")