Clarify doc comments in request.go, claim.go

README.md

@@ -1,3 +1,5 @@
 # xgbsel
 
+[![Go Reference](https://pkg.go.dev/badge/git.tebibyte.media/tomo/xgbsel.svg)](https://pkg.go.dev/git.tebibyte.media/tomo/xgbsel)
+
 Easy clipboard/selection manipulation and access with xgb and xgbutil.

claim.go

@@ -102,7 +102,8 @@ func (claim *Claim) fulfillSelectionRequest (
 }
 
 // While the selection claim is active, HandleSelectionRequest should be called
-// when the owner window recieves a SelectionRequest event.
+// when the owner window recieves a SelectionRequest event. This must be
+// registered as an event handler manually.
 func (claim *Claim) HandleSelectionRequest (
 	connection *xgbutil.XUtil,
 	event xevent.SelectionRequestEvent,

data.go

@@ -3,18 +3,25 @@ package xgbsel
 import "io"
 import "strings"
 
-// Data represents a polymorphic data structure
+// Data represents X selection data.
 type Data interface {
+	// Convert converts the data to the specified target and returns it. If
+	// the target is not supported, this behavior will return false for ok.
 	Convert (Target) (reader io.ReadSeekCloser, ok bool)
+
+	// Supported returns a slice of targets that Convert can accept. This
+	// can just be the result of MimeToTargets.
 	Supported () []Target
 }
 
 // Target represents an X selection target. It defines the type of data stored
-// within an X selection. This data may be a mime type, or a more specific name
+// within an X selection. This data may be a MIME type, or a more specific name
 // that is unique to X. A list of these names can be found here:
 // https://tronche.com/gui/x/icccm/sec-2.html#s-2.6.2
 type Target string
 
+// Confidence represents how accurate a conversion from a target to a MIME type
+// is.
 type Confidence int; const (
 	ConfidenceNone Confidence = iota
 	ConfidencePartial
@@ -23,9 +30,10 @@ type Confidence int; const (
 
 // ToMime converts the specified target to a MIME type. Because a single MIME
 // type may correspond to several targets, a confidence value is returned
-// representing how good of a match it is. If data is represented by multiple
-// targets, they can be checked one after the other and the one with the highest
-// confidence value chosen.
+// representing how one-to-one of a match it is. If some data is represented by
+// multiple targets, they can each be checked individually and the one with the
+// highest confidence value can be chosen. If a target cannot be converted to a
+// MIME type, ("", ConfidenceNone) is returned.
 func (target Target) ToMime () (string, Confidence) {
 	// TODO: add other stuff. reference this table:
 	// https://tronche.com/gui/x/icccm/sec-2.html#s-2.6.2
@@ -58,8 +66,10 @@ func (target Target) ToMime () (string, Confidence) {
 	}
 }
 
-// MimeToTargets returns a list of targets that correspond to a specified MIME
-// type.
+// MimeToTargets returns a slice of targets that correspond to a specified MIME
+// type. The MIME type itself is always the first item of the slice. All targets
+// returned by this function are guaranteed to convert to the given MIME type
+// when ToMime is called on them.
 func MimeToTargets (mime string) []Target {
 	targets := []Target { Target(mime) }
 	switch mime {

examples/paste/main.go

@@ -6,10 +6,10 @@ import "io"
 import "log"
 import "github.com/jezek/xgbutil"
 import "github.com/jezek/xgb/xproto"
+import "git.tebibyte.media/tomo/xgbsel"
 import "github.com/jezek/xgbutil/xprop"
 import "github.com/jezek/xgbutil/xevent"
 import "github.com/jezek/xgbutil/xwindow"
-import "git.tebibyte.media/sashakoshka/xgbsel"
 
 type requestor struct {
 	window *xwindow.Window

go.mod

@@ -1,4 +1,4 @@
-module git.tebibyte.media/sashakoshka/xgbsel
+module git.tebibyte.media/tomo/xgbsel
 
 go 1.11
 

request.go

@@ -106,7 +106,8 @@ func (request *Request) open () bool {
 }
 
 // While the selection request is active, HandleSelectionNotify should be called
-// when the requesting window recieves a SelectionNotify event.
+// when the requesting window recieves a SelectionNotify event. This must be
+// registered as an event handler manually.
 func (request *Request) HandleSelectionNotify (
 	connection *xgbutil.XUtil,
 	event xevent.SelectionNotifyEvent,
@@ -237,7 +238,8 @@ func (request *Request) HandleSelectionNotify (
 }
 
 // While the selection request is active, HandlePropertyNotify should be called
-// when the requesting window recieves a PropertyNotify event.
+// when the requesting window recieves a PropertyNotify event. This must be
+// registered as an event handler manually.
 func (request *Request) HandlePropertyNotify (
 	connection *xgbutil.XUtil,
 	event xevent.PropertyNotifyEvent,