Improve doc comments

dial.go

@@ -5,23 +5,19 @@ import "context"
 import "crypto/tls"
 import "github.com/quic-go/quic-go"
 
-// TODO: dial should be super simple like it is now, and there should be a
-// "dialer" which the dial function dial configures automaticaly, but the dialer
-// should offer much more options when used directlym
-
-// Dial opens a connection to a server. The network must be one of "udp",
-// "udp4", "udp6", or "unixgram".
+// Dial opens a connection to a server. The network must be one of "quic",
+// "quic4", (IPv4-only) "quic6" (IPv6-only), or "unix".
 func Dial(ctx context.Context, network, address string) (Conn, error) {
 	return (Dialer { }).Dial(ctx, network, address)
 }
 
-// TODO: export when there are options here
+// Dialer allows for further configuration of the dialing process.
 type Dialer struct {
 	TLSConfig *tls.Config
 }
 
 // Dial opens a connection to a server. The network must be one of "quic",
-// "quic4", "quic6", or "unix".
+// "quic4", (IPv4-only) "quic6" (IPv6-only), or "unix".
 func (diale Dialer) Dial(ctx context.Context, network, address string) (Conn, error) {
 	switch network {
 	case "quic", "quic4", "quic6": return diale.dialQUIC(ctx, network, address)

message.go

@@ -4,8 +4,10 @@ import "fmt"
 import "encoding"
 import "git.tebibyte.media/sashakoshka/hopp/tape"
 
-// Message is any object that is both a binary marshaler and unmarshaler.
+// Message is any object that can be sent or received over a HOPP connection.
 type Message interface {
+	// Method returns the method number of the message. This must be unique
+	// within the protocol, and should not change between calls.
 	Method() uint16
 	encoding.BinaryMarshaler
 	encoding.BinaryUnmarshaler
@@ -13,12 +15,14 @@ type Message interface {
 
 var _ Message = new(MessageData)
 
-// MessageData can hold the structure of any message. It can be used to alter
-// a protocol at runtime, transmit data with arbitrary keys, etc. Bear in mind
-// that is less performant than generating code because it has to make extra
-// memory allocations.
+// MessageData represents a message that organizes its data into table pairs. It
+// can be used to alter a protocol at runtime, transmit data with arbitrary
+// keys, etc. Bear in mind that is less performant than generating code because
+// it has to make extra memory allocations and such.
 type MessageData struct {
+	// Methd holds the method number. This should only be set once.
 	Methd uint16
+	// Pairs maps tags to values.
 	Pairs map[uint16] []byte
 }
 
@@ -27,14 +31,16 @@ func (this *MessageData) Method() uint16 {
 	return this.Methd
 }
 
-// MarshalBinary implements the [encoding.BinaryMarshaler] interface.
+// MarshalBinary implements the [encoding.BinaryMarshaler] interface. The
+// message is encoded using TAPE (Table Pair Encoding).
 func (this *MessageData) MarshalBinary() ([]byte, error) {
 	buffer, err := tape.EncodePairs(this.Pairs)
 	if err != nil { return nil, fmt.Errorf("marshaling MessageData: %w", err) }
 	return buffer, nil
 }
 
-// UnmarshalBinary implements the [encoding.BinaryUnmarshaler] interface.
+// UnmarshalBinary implements the [encoding.BinaryUnmarshaler] interface. The
+// message is decoded using TAPE (Table Pair Encoding).
 func (this *MessageData) UnmarshalBinary(buffer []byte) error {
 	this.Pairs = make(map[uint16] []byte)
 	pairs, err := tape.DecodePairs(buffer)