proto: add example for GetExtension, SetExtension

(Adding an example to HasExtension as well seemed too much to me.)

The example message uses the same example names as the Generated Code Reference:
https://protobuf.dev/reference/go/go-generated-opaque/#extensions

The definition follows the Language Guide:
https://protobuf.dev/programming-guides/editions/#extensions

For golang/protobuf#1528

Change-Id: I7c5c4a0ac954678a5e0b10015374377b32bd7634
Reviewed-on: https://go-review.googlesource.com/c/protobuf/+/641876
Reviewed-by: Damien Neil <[email protected]>
LUCI-TryBot-Result: Go LUCI <[email protected]>
Reviewed-by: Chressie Himpel <[email protected]>

internal/testprotos/examples/ext/extexample.proto

@@ -0,0 +1,32 @@
+// Copyright 2024 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+edition = "2023";
+
+package goproto.proto.test;
+
+import "google/protobuf/go_features.proto";
+
+option go_package = "google.golang.org/protobuf/internal/testprotos/examples/ext";
+option features.(pb.go).api_level = API_OPAQUE;
+
+message Concert {
+  string headliner_name = 1;
+
+  extensions 100 to 199 [
+    declaration = {
+      number: 123,
+      full_name: ".goproto.proto.test.promo_id",
+      type: "int32",
+    },
+    // Ensures all field numbers in this extension range are declarations.
+    verification = DECLARATION
+  ];
+}
+
+// Typically, this extension would be declared in a separate file,
+// but for brevity, we declare the entire example in one file.
+extend Concert {
+  int32 promo_id = 123;
+}

proto/extension_test.go

@@ -18,6 +18,7 @@ import (
 	"google.golang.org/protobuf/runtime/protoimpl"
 	"google.golang.org/protobuf/testing/protocmp"
 
+	extpb "google.golang.org/protobuf/internal/testprotos/examples/ext"
 	legacy1pb "google.golang.org/protobuf/internal/testprotos/legacy/proto2_20160225_2fc053c5"
 	testpb "google.golang.org/protobuf/internal/testprotos/test"
 	test3pb "google.golang.org/protobuf/internal/testprotos/test3"
@@ -407,3 +408,38 @@ func TestFeatureResolution(t *testing.T) {
 		}
 	}
 }
+
+func concertDetails() *extpb.Concert {
+	concert := &extpb.Concert{}
+	concert.SetHeadlinerName("Go Protobuf Acapella Band")
+	proto.SetExtension(concert, extpb.E_PromoId, int32(2342))
+	return concert
+}
+
+func ExampleGetExtension() {
+	concert := concertDetails( /* req.ConcertID */ )
+	fmt.Printf("finding backend server for live stream %q\n", concert.GetHeadlinerName())
+
+	if proto.HasExtension(concert, extpb.E_PromoId) {
+		promoId := proto.GetExtension(concert, extpb.E_PromoId).(int32)
+		fmt.Printf("routing stream to high-priority backend (concert is part of promo %v)\n", promoId)
+	} else {
+		fmt.Printf("routing stream to default backend\n")
+	}
+
+	// Output:
+	// finding backend server for live stream "Go Protobuf Acapella Band"
+	// routing stream to high-priority backend (concert is part of promo 2342)
+}
+
+func ExampleSetExtension() {
+	concert := extpb.Concert_builder{
+		HeadlinerName: proto.String("Go Protobuf Acapella Band"),
+	}.Build()
+	fmt.Printf("Has PromoId? %v\n", proto.HasExtension(concert, extpb.E_PromoId))
+	proto.SetExtension(concert, extpb.E_PromoId, int32(2342))
+	fmt.Printf("Has PromoId? %v\n", proto.HasExtension(concert, extpb.E_PromoId))
+	// Output:
+	// Has PromoId? false
+	// Has PromoId? true
+}