*: Linkify documentation

So that whenever documentation references a type or method, it is
displayed as clickable link in godoc. In my view it is especially useful
to have reference from top-level package overview to things it
references and explains.

Here is, for example, how top-level documentation looks before this patch:

https://lab.nexedi.com/kirr/misc/-/raw/d6c5394c/ogórek/godoc-nolinks.png

and after this patch:

https://lab.nexedi.com/kirr/misc/-/raw/d6c5394c/ogórek/godoc-links.png

The markup syntax for how to turn text into links is explained at

https://tip.golang.org/doc/comment#links

dict.go

@@ -22,10 +22,10 @@ import (
 // used as key, and all int(1), float64(1.0) and big.Int(1) are considered to be
 // equal.
 //
-// For strings, similarly to Python3, Bytes and string are considered to be not
+// For strings, similarly to Python3, [Bytes] and string are considered to be not
 // equal, even if their underlying content is the same. However with same
-// underlying content ByteString, because it represents str type from Python2,
-// is treated equal to both Bytes and string.
+// underlying content [ByteString], because it represents str type from Python2,
+// is treated equal to both [Bytes] and string.
 //
 // See PyDict mode documentation in top-level package overview for details.
 //

doc.go

 // Package ogórek(*) is a library for decoding/encoding Python's pickle format.
 //
-// Use Decoder to decode a pickle from input stream, for example:
+// Use [Decoder] to decode a pickle from input stream, for example:
 //
 //	d := ogórek.NewDecoder(r)
 //	obj, err := d.Decode() // obj is interface{} representing decoded Python object
 //
-// Use Encoder to encode an object as pickle into output stream, for example:
+// Use [Encoder] to encode an object as pickle into output stream, for example:
 //
 //	e := ogórek.NewEncoder(w)
 //	err := e.Encode(obj)
@@ -36,7 +36,7 @@
 //      dict    ↔  map[any]any                       PyDict=n mode, default
 //              ←  ogórek.Dict
 //
-// With PyDict=y mode, however, Python dicts are decoded as ogórek.Dict which
+// With PyDict=y mode, however, Python dicts are decoded as [ogórek.Dict] which
 // mirrors behaviour of Python dict with respect to keys equality, and with
 // respect to which types are allowed to be used as keys.
 //
@@ -48,7 +48,7 @@
 // str and py2 unicode are decoded into string with py2 str being considered
 // as UTF-8 encoded. Correspondingly for protocol ≤ 2 Go string is encoded as
 // UTF-8 encoded py2 str, and for protocol ≥ 3 as py3 str / py2 unicode.
-// ogórek.ByteString can be used to produce bytestring objects after encoding
+// [ogórek.ByteString] can be used to produce bytestring objects after encoding
 // even for protocol ≥ 3. This mode tries to match Go string with str type of
 // target Python depending on protocol version, but looses information after
 // decoding/encoding cycle:
@@ -58,7 +58,7 @@
 //	py2 str      ←  ogórek.ByteString
 //
 // However with StrictUnicode=y mode there is 1-1 mapping in between py2
-// unicode / py3 str vs Go string, and between py2 str vs ogórek.ByteString.
+// unicode / py3 str vs Go string, and between py2 str vs [ogórek.ByteString].
 // In this mode decoding/encoding and encoding/decoding operations are always
 // identity with respect to strings:
 //
@@ -74,7 +74,7 @@
 //
 //
 //
-// Python classes and instances are mapped to Class and Call, for example:
+// Python classes and instances are mapped to [Class] and [Call], for example:
 //
 //	Python				Go
 //	------	   			--
@@ -127,7 +127,7 @@
 // how one in-RAM object can have a reference to another in-RAM object.
 //
 // When a pickle with such persistent reference is decoded, ogórek represents
-// the reference with Ref placeholder similarly to Class and Call. However it
+// the reference with [Ref] placeholder similarly to [Class] and [Call]. However it
 // is possible to hook into decoding and process such references in application
 // specific way, for example loading the referenced object from the database:
 //
@@ -152,7 +152,7 @@
 // expected to handle both with the same effect. To help handling decoded
 // values with such differences ogórek provides utilities that bring objects
 // to common type irregardless of which type variant was used in the pickle
-// stream. For example AsInt64 tries to represent unpickled value as int64 if
+// stream. For example [AsInt64] tries to represent unpickled value as int64 if
 // possible and errors if not.
 //
 // For strings the situation is similar, but a bit different.
@@ -160,20 +160,20 @@
 // bytes type. However on Python2 strings are bytestrings and could contain
 // both text and binary data. In the default mode py2 strings, the same way as
 // py2 unicode, are decoded into Go strings. However in StrictUnicode mode py2
-// strings are decoded into ByteString - the type specially dedicated to
+// strings are decoded into [ByteString] - the type specially dedicated to
 // represent them on Go side. There are two utilities to help programs handle
 // all those bytes/string data in the pickle stream in uniform way:
 //
-//     - the program should use AsString if it expects text   data -
+//     - the program should use [AsString] if it expects text   data -
 //       either unicode string, or byte string.
-//     - the program should use AsBytes  if it expects binary data -
+//     - the program should use [AsBytes]  if it expects binary data -
 //	 either bytes, or byte string.
 //
 // Using the helpers fits into Python3 strings/bytes model but also allows to
 // handle the data generated from under Python2.
 //
-// Similarly Dict considers ByteString to be equal to both string and Bytes
-// with the same underlying content. This allows programs to access Dict via
+// Similarly [Dict] considers [ByteString] to be equal to both string and [Bytes]
+// with the same underlying content. This allows programs to access [Dict] via
 // string/bytes keys following Python3 model, while still being able to handle
 // dictionaries generated from under Python2.
 //

encode.go

@@ -31,7 +31,7 @@ type Encoder struct {
 	config *EncoderConfig
 }
 
-// EncoderConfig allows to tune Encoder.
+// EncoderConfig allows to tune [Encoder].
 type EncoderConfig struct {
 	// Protocol specifies which pickle protocol version should be used.
 	Protocol int
@@ -53,7 +53,7 @@ type EncoderConfig struct {
 	StrictUnicode bool
 }
 
-// NewEncoder returns a new Encoder with the default configuration.
+// NewEncoder returns a new [Encoder] with the default configuration.
 //
 // The encoder will emit pickle stream into w.
 func NewEncoder(w io.Writer) *Encoder {
@@ -63,7 +63,7 @@ func NewEncoder(w io.Writer) *Encoder {
 	})
 }
 
-// NewEncoderWithConfig is similar to NewEncoder, but returns the encoder with the specified configuration.
+// NewEncoderWithConfig is similar to [NewEncoder], but returns the encoder with the specified configuration.
 //
 // config must not be nil.
 func NewEncoderWithConfig(w io.Writer, config *EncoderConfig) *Encoder {

ogorek.go

@@ -168,7 +168,7 @@ type Decoder struct {
 	protocol int
 }
 
-// DecoderConfig allows to tune Decoder.
+// DecoderConfig allows to tune [Decoder].
 type DecoderConfig struct {
 	// PersistentLoad, if !nil, will be used by decoder to handle persistent references.
 	//
@@ -196,7 +196,7 @@ type DecoderConfig struct {
 	PyDict bool
 }
 
-// NewDecoder returns a new Decoder with the default configuration.
+// NewDecoder returns a new [Decoder] with the default configuration.
 //
 // The decoder will decode the pickle stream in r.
 func NewDecoder(r io.Reader) *Decoder {
@@ -634,7 +634,7 @@ func (d *Decoder) loadNone() error {
 // See https://docs.python.org/3/library/pickle.html#pickle-persistent for details.
 //
 // See DecoderConfig.PersistentLoad and EncoderConfig.PersistentRef for ways to
-// tune Decoder and Encoder to handle persistent references with user-specified
+// tune [Decoder] and [Encoder] to handle persistent references with user-specified
 // application logic.
 type Ref struct {
 	// persistent ID of referenced object.

typeconv.go

@@ -28,10 +28,10 @@ func AsInt64(x interface{}) (int64, error) {
 
 // AsBytes tries to represent unpickled value as Bytes.
 //
-// It succeeds only if the value is either Bytes, or ByteString.
+// It succeeds only if the value is either [Bytes], or [ByteString].
 // It does not succeed if the value is string or any other type.
 //
-// ByteString is treated related to Bytes because ByteString represents str
+// [ByteString] is treated related to [Bytes] because [ByteString] represents str
 // type from py2 which can contain both string and binary data.
 func AsBytes(x interface{}) (Bytes, error) {
 	switch x := x.(type) {
@@ -45,10 +45,10 @@ func AsBytes(x interface{}) (Bytes, error) {
 
 // AsString tries to represent unpickled value as string.
 //
-// It succeeds only if the value is either string, or ByteString.
-// It does not succeed if the value is Bytes or any other type.
+// It succeeds only if the value is either string, or [ByteString].
+// It does not succeed if the value is [Bytes] or any other type.
 //
-// ByteString is treated related to string because ByteString represents str
+// [ByteString] is treated related to string because [ByteString] represents str
 // type from py2 which can contain both string and binary data.
 func AsString(x interface{}) (string, error) {
 	switch x := x.(type) {