claim.go

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

data.go

@@ -3,25 +3,18 @@ package xgbsel
 import "io"
 import "strings"
 
-// Data represents X selection data.
+// Data represents a polymorphic data structure
 type Data interface {
-	// Convert converts the data to the specified target and returns it. If
+	Convert   (Target) (reader io.ReadSeekCloser, ok bool)
-	// 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
@@ -30,10 +23,9 @@ 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 one-to-one of a match it is. If some data is represented by
+// representing how good of a match it is. If data is represented by multiple
-// multiple targets, they can each be checked individually and the one with the
+// targets, they can be checked one after the other and the one with the highest
-// highest confidence value can be chosen. If a target cannot be converted to a
+// confidence value chosen.
-// 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
@@ -66,10 +58,8 @@ func (target Target) ToMime () (string, Confidence) {
 	}
 }
 
-// MimeToTargets returns a slice of targets that correspond to a specified MIME
+// MimeToTargets returns a list of targets that correspond to a specified MIME
-// type. The MIME type itself is always the first item of the slice. All targets
+// type.
-// 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 {

request.go

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