jsonpb: strictly document JSONPBMarshaler and JSONPBUnmarshaler behavior (#662)

Strictly document that custom JSONPBMarshaler and JSONPBUnmarshaler must
properly follow the JSON to proto specification:
	https://developers.google.com/protocol-buffers/docs/proto3#json

These interfaces are currently necessary since there is no high-level API
for proto reflection. However, as we prepare to move to a world where there is
first-class support for proto reflection, these interfaces should be deprecated.
When we eventually have proto reflection, and implement jsonpb entirely
in terms of reflection, then it should not matter whether we called these
custom marshalers or not since they should both implement the same specification.

Note that this documentation is already implied by the fact that this whole
package implements the proto-JSON specification and in order for it to do so,
it implies that any custom interfaces it calls also follows the specification.
We strictly document this to dissuade improper implementations.

Author: dsnet

jsonpb/jsonpb.go

@@ -106,6 +106,9 @@ func defaultResolveAny(typeUrl string) (proto.Message, error) {
 // way they are marshaled to JSON. Messages that implement this should
 // also implement JSONPBUnmarshaler so that the custom format can be
 // parsed.
+//
+// The JSON marshaling must follow the proto to JSON specification:
+//	https://developers.google.com/protocol-buffers/docs/proto3#json
 type JSONPBMarshaler interface {
 	MarshalJSONPB(*Marshaler) ([]byte, error)
 }
@@ -114,6 +117,9 @@ type JSONPBMarshaler interface {
 // the way they are unmarshaled from JSON. Messages that implement this
 // should also implement JSONPBMarshaler so that the custom format can be
 // produced.
+//
+// The JSON unmarshaling must follow the JSON to proto specification:
+//	https://developers.google.com/protocol-buffers/docs/proto3#json
 type JSONPBUnmarshaler interface {
 	UnmarshalJSONPB(*Unmarshaler, []byte) error
 }