ax(ueps): replace prose comments with usage examples (AX principle 2)

NewBuilder, MarshalAndSign, ReadAndVerify, PacketBuilder, and ParsedPacket
comments now show concrete call-site examples with real values instead of
restating what the type signatures already convey.

Co-Authored-By: Charon <charon@lethean.io>

pkg/ueps/packet.go

@@ -29,13 +29,15 @@ type UEPSHeader struct {
 	ThreatScore  uint16 // 0-65535
 }
 
-// PacketBuilder helps construct a signed UEPS frame
+// builder := ueps.NewBuilder(intentID, payload); frame, _ := builder.MarshalAndSign(secret)
 type PacketBuilder struct {
 	Header  UEPSHeader
 	Payload []byte
 }
 
-// NewBuilder creates a packet context for a specific intent
+// builder := ueps.NewBuilder(0x01, []byte("hello"))
+// builder.Header.ThreatScore = 100
+// frame, err := builder.MarshalAndSign(sharedSecret)
 func NewBuilder(intentID uint8, payload []byte) *PacketBuilder {
 	return &PacketBuilder{
 		Header: UEPSHeader{
@@ -49,7 +51,7 @@ func NewBuilder(intentID uint8, payload []byte) *PacketBuilder {
 	}
 }
 
-// MarshalAndSign generates the final byte stream using the shared secret
+// frame, err := builder.MarshalAndSign([]byte("my-shared-secret"))
 func (p *PacketBuilder) MarshalAndSign(sharedSecret []byte) ([]byte, error) {
 	buf := new(bytes.Buffer)
 

pkg/ueps/reader.go

@@ -11,14 +11,14 @@ import (
 	"io"
 )
 
-// ParsedPacket holds the verified data
+// packet.Header.ThreatScore, packet.Header.IntentID, packet.Payload
 type ParsedPacket struct {
 	Header  UEPSHeader
 	Payload []byte
 }
 
-// ReadAndVerify reads a UEPS frame from the stream and validates the HMAC.
-// It consumes the stream up to the end of the packet.
+// packet, err := ueps.ReadAndVerify(bufio.NewReader(conn), []byte("my-shared-secret"))
+// if err != nil { /* integrity violation or truncated frame */ }
 func ReadAndVerify(r *bufio.Reader, sharedSecret []byte) (*ParsedPacket, error) {
 	// Buffer to reconstruct the data for HMAC verification
 	// We have to "record" what we read to verify the signature later.