From 02dbcacd2803b3da8ff82c8ce918b9cb43577038 Mon Sep 17 00:00:00 2001 From: "sashakoshka@tebibyte.media" Date: Sun, 19 Jan 2025 17:09:20 -0500 Subject: [PATCH] Improve doc comments --- dial.go | 12 ++++-------- message.go | 20 +++++++++++++------- 2 files changed, 17 insertions(+), 15 deletions(-) diff --git a/dial.go b/dial.go index bf1cb64..f4cdd1d 100644 --- a/dial.go +++ b/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) diff --git a/message.go b/message.go index dc8f77c..8bb8bd1 100644 --- a/message.go +++ b/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)