all: modernize documentation

Modernize the documentation across the entire module
to make use of the newer ability to linkify declarations.

Change-Id: I440f9a3f025ec6fadfd9cba59b1dfb57028bf3f1
Reviewed-on: https://go-review.googlesource.com/c/protobuf/+/309430
Reviewed-by: Michael Stapelberg <[email protected]>
Reviewed-by: Damien Neil <[email protected]>

compiler/protogen/protogen.go

@@ -5,8 +5,8 @@
 // Package protogen provides support for writing protoc plugins.
 //
 // Plugins for protoc, the Protocol Buffer compiler,
-// are programs which read a CodeGeneratorRequest message from standard input
-// and write a CodeGeneratorResponse message to standard output.
+// are programs which read a [pluginpb.CodeGeneratorRequest] message from standard input
+// and write a [pluginpb.CodeGeneratorResponse] message to standard output.
 // This package provides support for writing plugins which generate Go code.
 package protogen
 
@@ -44,11 +44,11 @@ const goPackageDocURL = "https://protobuf.dev/reference/go/go-generated#package"
 
 // Run executes a function as a protoc plugin.
 //
-// It reads a CodeGeneratorRequest message from os.Stdin, invokes the plugin
-// function, and writes a CodeGeneratorResponse message to os.Stdout.
+// It reads a [pluginpb.CodeGeneratorRequest] message from [os.Stdin], invokes the plugin
+// function, and writes a [pluginpb.CodeGeneratorResponse] message to [os.Stdout].
 //
 // If a failure occurs while reading or writing, Run prints an error to
-// os.Stderr and calls os.Exit(1).
+// [os.Stderr] and calls [os.Exit](1).
 func (opts Options) Run(f func(*Plugin) error) {
 	if err := run(opts, f); err != nil {
 		fmt.Fprintf(os.Stderr, "%s: %v\n", filepath.Base(os.Args[0]), err)
@@ -834,7 +834,7 @@ func newOneof(gen *Plugin, f *File, message *Message, desc protoreflect.OneofDes
 	}
 }
 
-// Extension is an alias of Field for documentation.
+// Extension is an alias of [Field] for documentation.
 type Extension = Field
 
 // A Service describes a service.
@@ -946,7 +946,7 @@ func (gen *Plugin) NewGeneratedFile(filename string, goImportPath GoImportPath)
 }
 
 // P prints a line to the generated output. It converts each parameter to a
-// string following the same rules as fmt.Print. It never inserts spaces
+// string following the same rules as [fmt.Print]. It never inserts spaces
 // between parameters.
 func (g *GeneratedFile) P(v ...interface{}) {
 	for _, x := range v {
@@ -983,14 +983,14 @@ func (g *GeneratedFile) QualifiedGoIdent(ident GoIdent) string {
 
 // Import ensures a package is imported by the generated file.
 //
-// Packages referenced by QualifiedGoIdent are automatically imported.
+// Packages referenced by [GeneratedFile.QualifiedGoIdent] are automatically imported.
 // Explicitly importing a package with Import is generally only necessary
 // when the import will be blank (import _ "package").
 func (g *GeneratedFile) Import(importPath GoImportPath) {
 	g.manualImports[importPath] = true
 }
 
-// Write implements io.Writer.
+// Write implements [io.Writer].
 func (g *GeneratedFile) Write(p []byte) (n int, err error) {
 	return g.buf.Write(p)
 }
@@ -1000,8 +1000,8 @@ func (g *GeneratedFile) Skip() {
 	g.skip = true
 }
 
-// Unskip reverts a previous call to Skip, re-including the generated file in
-// the plugin output.
+// Unskip reverts a previous call to [GeneratedFile.Skip],
+// re-including the generated file in the plugin output.
 func (g *GeneratedFile) Unskip() {
 	g.skip = false
 }
@@ -1013,7 +1013,7 @@ func (g *GeneratedFile) Unskip() {
 // struct field.  The "T.sel" syntax is used to identify the method or field
 // 'sel' on type 'T'.
 //
-// Deprecated: Use the AnnotateSymbol method instead.
+// Deprecated: Use the [GeneratedFile.AnnotateSymbol] method instead.
 func (g *GeneratedFile) Annotate(symbol string, loc Location) {
 	g.AnnotateSymbol(symbol, Annotation{Location: loc})
 }
@@ -1319,7 +1319,7 @@ func (c Comments) String() string {
 // file for which we are generating bindings.
 //
 // Lookups consult the local type registry first and fall back to the base type
-// registry which defaults to protoregistry.GlobalTypes
+// registry which defaults to protoregistry.GlobalTypes.
 type extensionRegistry struct {
 	base  *protoregistry.Types
 	local *protoregistry.Types

encoding/protodelim/protodelim.go

@@ -42,7 +42,7 @@ func (o MarshalOptions) MarshalTo(w io.Writer, m proto.Message) (int, error) {
 // MarshalTo writes a varint size-delimited wire-format message to w
 // with the default options.
 //
-// See the documentation for MarshalOptions.MarshalTo.
+// See the documentation for [MarshalOptions.MarshalTo].
 func MarshalTo(w io.Writer, m proto.Message) (int, error) {
 	return MarshalOptions{}.MarshalTo(w, m)
 }
@@ -61,7 +61,7 @@ type UnmarshalOptions struct {
 const defaultMaxSize = 4 << 20 // 4 MiB, corresponds to the default gRPC max request/response size
 
 // SizeTooLargeError is an error that is returned when the unmarshaler encounters a message size
-// that is larger than its configured MaxSize.
+// that is larger than its configured [UnmarshalOptions.MaxSize].
 type SizeTooLargeError struct {
 	// Size is the varint size of the message encountered
 	// that was larger than the provided MaxSize.
@@ -75,8 +75,8 @@ func (e *SizeTooLargeError) Error() string {
 	return fmt.Sprintf("message size %d exceeded unmarshaler's maximum configured size %d", e.Size, e.MaxSize)
 }
 
-// Reader is the interface expected by UnmarshalFrom.
-// It is implemented by *bufio.Reader.
+// Reader is the interface expected by [UnmarshalFrom].
+// It is implemented by *[bufio.Reader].
 type Reader interface {
 	io.Reader
 	io.ByteReader
@@ -86,11 +86,11 @@ type Reader interface {
 // from r.
 // The provided message must be mutable (e.g., a non-nil pointer to a message).
 //
-// The error is io.EOF error only if no bytes are read.
+// The error is [io.EOF] error only if no bytes are read.
 // If an EOF happens after reading some but not all the bytes,
 // UnmarshalFrom returns a non-io.EOF error.
 // In particular if r returns a non-io.EOF error, UnmarshalFrom returns it unchanged,
-// and if only a size is read with no subsequent message, io.ErrUnexpectedEOF is returned.
+// and if only a size is read with no subsequent message, [io.ErrUnexpectedEOF] is returned.
 func (o UnmarshalOptions) UnmarshalFrom(r Reader, m proto.Message) error {
 	var sizeArr [binary.MaxVarintLen64]byte
 	sizeBuf := sizeArr[:0]
@@ -154,7 +154,7 @@ func (o UnmarshalOptions) UnmarshalFrom(r Reader, m proto.Message) error {
 // from r with the default options.
 // The provided message must be mutable (e.g., a non-nil pointer to a message).
 //
-// See the documentation for UnmarshalOptions.UnmarshalFrom.
+// See the documentation for [UnmarshalOptions.UnmarshalFrom].
 func UnmarshalFrom(r Reader, m proto.Message) error {
 	return UnmarshalOptions{}.UnmarshalFrom(r, m)
 }

encoding/protojson/decode.go

@@ -23,7 +23,7 @@ import (
 	"google.golang.org/protobuf/reflect/protoregistry"
 )
 
-// Unmarshal reads the given []byte into the given proto.Message.
+// Unmarshal reads the given []byte into the given [proto.Message].
 // The provided message must be mutable (e.g., a non-nil pointer to a message).
 func Unmarshal(b []byte, m proto.Message) error {
 	return UnmarshalOptions{}.Unmarshal(b, m)
@@ -49,7 +49,7 @@ type UnmarshalOptions struct {
 	}
 }
 
-// Unmarshal reads the given []byte and populates the given proto.Message
+// Unmarshal reads the given []byte and populates the given [proto.Message]
 // using options in the UnmarshalOptions object.
 // It will clear the message first before setting the fields.
 // If it returns an error, the given message may be partially set.

encoding/protojson/doc.go

@@ -6,6 +6,6 @@
 // format. It follows the guide at
 // https://protobuf.dev/programming-guides/proto3#json.
 //
-// This package produces a different output than the standard "encoding/json"
+// This package produces a different output than the standard [encoding/json]
 // package, which does not operate correctly on protocol buffer messages.
 package protojson

encoding/protojson/encode.go

@@ -31,7 +31,7 @@ func Format(m proto.Message) string {
 	return MarshalOptions{Multiline: true}.Format(m)
 }
 
-// Marshal writes the given proto.Message in JSON format using default options.
+// Marshal writes the given [proto.Message] in JSON format using default options.
 // Do not depend on the output being stable. It may change over time across
 // different versions of the program.
 func Marshal(m proto.Message) ([]byte, error) {
@@ -102,7 +102,7 @@ func (o MarshalOptions) Format(m proto.Message) string {
 	return string(b)
 }
 
-// Marshal marshals the given proto.Message in the JSON format using options in
+// Marshal marshals the given [proto.Message] in the JSON format using options in
 // MarshalOptions. Do not depend on the output being stable. It may change over
 // time across different versions of the program.
 func (o MarshalOptions) Marshal(m proto.Message) ([]byte, error) {

encoding/prototext/decode.go

@@ -21,7 +21,7 @@ import (
 	"google.golang.org/protobuf/reflect/protoregistry"
 )
 
-// Unmarshal reads the given []byte into the given proto.Message.
+// Unmarshal reads the given []byte into the given [proto.Message].
 // The provided message must be mutable (e.g., a non-nil pointer to a message).
 func Unmarshal(b []byte, m proto.Message) error {
 	return UnmarshalOptions{}.Unmarshal(b, m)
@@ -51,7 +51,7 @@ type UnmarshalOptions struct {
 	}
 }
 
-// Unmarshal reads the given []byte and populates the given proto.Message
+// Unmarshal reads the given []byte and populates the given [proto.Message]
 // using options in the UnmarshalOptions object.
 // The provided message must be mutable (e.g., a non-nil pointer to a message).
 func (o UnmarshalOptions) Unmarshal(b []byte, m proto.Message) error {

encoding/prototext/encode.go

@@ -33,7 +33,7 @@ func Format(m proto.Message) string {
 	return MarshalOptions{Multiline: true}.Format(m)
 }
 
-// Marshal writes the given proto.Message in textproto format using default
+// Marshal writes the given [proto.Message] in textproto format using default
 // options. Do not depend on the output being stable. It may change over time
 // across different versions of the program.
 func Marshal(m proto.Message) ([]byte, error) {
@@ -97,7 +97,7 @@ func (o MarshalOptions) Format(m proto.Message) string {
 	return string(b)
 }
 
-// Marshal writes the given proto.Message in textproto format using options in
+// Marshal writes the given [proto.Message] in textproto format using options in
 // MarshalOptions object. Do not depend on the output being stable. It may
 // change over time across different versions of the program.
 func (o MarshalOptions) Marshal(m proto.Message) ([]byte, error) {

encoding/protowire/wire.go

@@ -6,7 +6,7 @@
 // See https://protobuf.dev/programming-guides/encoding.
 //
 // For marshaling and unmarshaling entire protobuf messages,
-// use the "google.golang.org/protobuf/proto" package instead.
+// use the [google.golang.org/protobuf/proto] package instead.
 package protowire
 
 import (
@@ -87,7 +87,7 @@ func ParseError(n int) error {
 
 // ConsumeField parses an entire field record (both tag and value) and returns
 // the field number, the wire type, and the total length.
-// This returns a negative length upon an error (see ParseError).
+// This returns a negative length upon an error (see [ParseError]).
 //
 // The total length includes the tag header and the end group marker (if the
 // field is a group).
@@ -104,8 +104,8 @@ func ConsumeField(b []byte) (Number, Type, int) {
 }
 
 // ConsumeFieldValue parses a field value and returns its length.
-// This assumes that the field Number and wire Type have already been parsed.
-// This returns a negative length upon an error (see ParseError).
+// This assumes that the field [Number] and wire [Type] have already been parsed.
+// This returns a negative length upon an error (see [ParseError]).
 //
 // When parsing a group, the length includes the end group marker and
 // the end group is verified to match the starting field number.
@@ -164,7 +164,7 @@ func AppendTag(b []byte, num Number, typ Type) []byte {
 }
 
 // ConsumeTag parses b as a varint-encoded tag, reporting its length.
-// This returns a negative length upon an error (see ParseError).
+// This returns a negative length upon an error (see [ParseError]).
 func ConsumeTag(b []byte) (Number, Type, int) {
 	v, n := ConsumeVarint(b)
 	if n < 0 {
@@ -263,7 +263,7 @@ func AppendVarint(b []byte, v uint64) []byte {
 }
 
 // ConsumeVarint parses b as a varint-encoded uint64, reporting its length.
-// This returns a negative length upon an error (see ParseError).
+// This returns a negative length upon an error (see [ParseError]).
 func ConsumeVarint(b []byte) (v uint64, n int) {
 	var y uint64
 	if len(b) <= 0 {
@@ -384,7 +384,7 @@ func AppendFixed32(b []byte, v uint32) []byte {
 }
 
 // ConsumeFixed32 parses b as a little-endian uint32, reporting its length.
-// This returns a negative length upon an error (see ParseError).
+// This returns a negative length upon an error (see [ParseError]).
 func ConsumeFixed32(b []byte) (v uint32, n int) {
 	if len(b) < 4 {
 		return 0, errCodeTruncated
@@ -412,7 +412,7 @@ func AppendFixed64(b []byte, v uint64) []byte {
 }
 
 // ConsumeFixed64 parses b as a little-endian uint64, reporting its length.
-// This returns a negative length upon an error (see ParseError).
+// This returns a negative length upon an error (see [ParseError]).
 func ConsumeFixed64(b []byte) (v uint64, n int) {
 	if len(b) < 8 {
 		return 0, errCodeTruncated
@@ -432,7 +432,7 @@ func AppendBytes(b []byte, v []byte) []byte {
 }
 
 // ConsumeBytes parses b as a length-prefixed bytes value, reporting its length.
-// This returns a negative length upon an error (see ParseError).
+// This returns a negative length upon an error (see [ParseError]).
 func ConsumeBytes(b []byte) (v []byte, n int) {
 	m, n := ConsumeVarint(b)
 	if n < 0 {
@@ -456,7 +456,7 @@ func AppendString(b []byte, v string) []byte {
 }
 
 // ConsumeString parses b as a length-prefixed bytes value, reporting its length.
-// This returns a negative length upon an error (see ParseError).
+// This returns a negative length upon an error (see [ParseError]).
 func ConsumeString(b []byte) (v string, n int) {
 	bb, n := ConsumeBytes(b)
 	return string(bb), n
@@ -471,7 +471,7 @@ func AppendGroup(b []byte, num Number, v []byte) []byte {
 // ConsumeGroup parses b as a group value until the trailing end group marker,
 // and verifies that the end marker matches the provided num. The value v
 // does not contain the end marker, while the length does contain the end marker.
-// This returns a negative length upon an error (see ParseError).
+// This returns a negative length upon an error (see [ParseError]).
 func ConsumeGroup(num Number, b []byte) (v []byte, n int) {
 	n = ConsumeFieldValue(num, StartGroupType, b)
 	if n < 0 {
@@ -495,8 +495,8 @@ func SizeGroup(num Number, n int) int {
 	return n + SizeTag(num)
 }
 
-// DecodeTag decodes the field Number and wire Type from its unified form.
-// The Number is -1 if the decoded field number overflows int32.
+// DecodeTag decodes the field [Number] and wire [Type] from its unified form.
+// The [Number] is -1 if the decoded field number overflows int32.
 // Other than overflow, this does not check for field number validity.
 func DecodeTag(x uint64) (Number, Type) {
 	// NOTE: MessageSet allows for larger field numbers than normal.
@@ -506,7 +506,7 @@ func DecodeTag(x uint64) (Number, Type) {
 	return Number(x >> 3), Type(x & 7)
 }
 
-// EncodeTag encodes the field Number and wire Type into its unified form.
+// EncodeTag encodes the field [Number] and wire [Type] into its unified form.
 func EncodeTag(num Number, typ Type) uint64 {
 	return uint64(num)<<3 | uint64(typ&7)
 }

proto/decode.go

@@ -69,7 +69,7 @@ func (o UnmarshalOptions) Unmarshal(b []byte, m Message) error {
 // UnmarshalState parses a wire-format message and places the result in m.
 //
 // This method permits fine-grained control over the unmarshaler.
-// Most users should use Unmarshal instead.
+// Most users should use [Unmarshal] instead.
 func (o UnmarshalOptions) UnmarshalState(in protoiface.UnmarshalInput) (protoiface.UnmarshalOutput, error) {
 	if o.RecursionLimit == 0 {
 		o.RecursionLimit = protowire.DefaultRecursionLimit