tree ba52a75f9853d5188d311bb504acff40525b09c0
parent 11bd559057bb9c65e24d1bd7f436d375323a8565
author Joe Tsai <joetsai@digital-static.net> 1533056686 -0700
committer GitHub <noreply@github.com> 1533056686 -0700
gpgsig -----BEGIN PGP SIGNATURE-----
 
 wsBcBAABCAAQBQJbYJauCRBK7hj4Ov3rIwAAdHIIAKrVDHm0BzUcd1s+J3LNfpE2
 XqBMoZGH+OfOgJi7aV4+/aUDG3k1i/ff89KIDE3KzBhqjCocjKP+DtAu3cwB7beD
 X0abGwrF7QBR1RnKQAnKNnx2rRloTAtSiNpSuWstEbajDnwd1Z6GCEpJm9cT3Vo5
 TM++eoxMVMvuC8YfXYBtUvlS3Hfhvty8Cn8gSF+46R1vxeCQpQpUFcL6QfK8ZiIN
 eDjJdjRy9/QnxGEC4FDbbYs6VRdnAm4Iouv3n6kH2LwMLhUnBXp3/ko/Q4rjsyiO
 vZpPLaepdEEKvO9Njmaxf+O6yzJR5mAtE3sCWHu0uheca1u6MEaISj9SQEev/tk=
 =9394
 -----END PGP SIGNATURE-----
 

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.