diff --git a/proto/encode.go b/proto/encode.go index 4fed202f..d8f0dbe4 100644 --- a/proto/encode.go +++ b/proto/encode.go @@ -71,6 +71,10 @@ type MarshalOptions struct { } // Marshal returns the wire-format encoding of m. +// +// This is the most convenient entry point for encoding a Protobuf message. +// +// See the [MarshalOptions] type if you need more control. func Marshal(m Message) ([]byte, error) { // Treat nil message interface as an empty message; nothing to output. if m == nil { diff --git a/proto/encode_test.go b/proto/encode_test.go index 0f76004a..388c85db 100644 --- a/proto/encode_test.go +++ b/proto/encode_test.go @@ -17,6 +17,7 @@ import ( "google.golang.org/protobuf/encoding/protowire" "google.golang.org/protobuf/proto" "google.golang.org/protobuf/reflect/protoreflect" + "google.golang.org/protobuf/types/known/durationpb" "google.golang.org/protobuf/internal/errors" orderpb "google.golang.org/protobuf/internal/testprotos/order" @@ -281,3 +282,30 @@ func TestEncodeEmpty(t *testing.T) { }) } } + +// This example illustrates how to marshal (encode) a Protobuf message struct +// literal into wire-format encoding. +// +// This example hard-codes a duration of 125ns for the illustration of struct +// fields, but note that you do not need to fill the fields of well-known types +// like duration.proto yourself. To convert a time.Duration, use +// [google.golang.org/protobuf/types/known/durationpb.New]. +func ExampleMarshal() { + b, err := proto.Marshal(&durationpb.Duration{ + Nanos: 125, + }) + if err != nil { + panic(err) + } + + fmt.Printf("125ns encoded into %d bytes of Protobuf wire format:\n% x\n", len(b), b) + + // You can use protoscope to explore the wire format: + // https://github.com/protocolbuffers/protoscope + // + // echo -n '10 7d' | xxd -r -ps | protoscope + // 2: 125 + + // Output: 125ns encoded into 2 bytes of Protobuf wire format: + // 10 7d +}