cleanup: add/fix comments

error.go

@@ -48,7 +48,8 @@ func onError(file *C.char, line C.int, funcName *C.char, errorObject *C.char, er
 
 // startProcessingXML is called whenever we enter a function exported by this package.
 // It locks the current goroutine to the current thread and establishes a thread-local
-// error object.
+// error object. If the library later calls onError then the error will be appended
+// to the error object associated with the current thread.
 func startProcessingXML() {
 	runtime.LockOSThread()
 	globalErrors[getThreadID()] = errset.ErrSet{}
@@ -62,7 +63,9 @@ func stopProcessingXML() {
 }
 
 // popError returns the global error for the current thread and resets it to
-// an empty error. Returns nil if no errors have occurred.
+// an empty error. Returns nil if no errors have occurred. This function must be
+// called after startProcessingXML() and before stopProcessingXML(). All three
+// functions must be called on the same goroutine.
 func popError() error {
 	threadID := getThreadID()
 	rv := globalErrors[threadID].ReturnValue()

error_thunk.go

@@ -1,9 +1,11 @@
 package xmlsec
 
 // onError_cgo is a C function that can be passed to xmlSecErrorsSetCallback which
-// in turn invokes the go function onError which captures the error.
+// in turn invokes the go function onError which captures errors generated by
+// libxmlsec.
+//
 // For reasons I do not completely understand, it must be defined in a different
-// file from onError
+// file from onError.
 
 // void onError_cgo(char *file, int line, char *funcName, char *errorObject, char *errorSubject, int reason, char *msg) {
 //   onError(file, line, funcName, errorObject, errorSubject, reason, msg);

thread_darwin.go

@@ -5,6 +5,9 @@ import "unsafe"
 // #include <pthread.h>
 import "C"
 
+// getThreadID returns an opaque value that is unique per OS thread.
 func getThreadID() uintptr {
+	// Darwin lacks a meaningful version of gettid() so instead we use
+	// ptread_self() as a proxy.
 	return uintptr(unsafe.Pointer(C.pthread_self()))
 }

thread_linux.go

@@ -2,6 +2,7 @@ package xmlsec
 
 import "syscall"
 
+// getThreadID returns an opaque value that is unique per OS thread
 func getThreadID() uintptr {
 	return uintptr(syscall.Gettid())
 }

xmldsig.go

@@ -36,7 +36,7 @@ type XMLIDOption struct {
 }
 
 // Sign returns a version of doc signed with key according to
-// the XML-DSIG standard. doc is a template document meaning
+// the XMLDSIG standard. doc is a template document meaning
 // that it contains an `http://www.w3.org/2000/09/xmldsig#Signature`
 // element whose properties define how and what to sign.
 func Sign(key []byte, doc []byte, opts SignatureOptions) ([]byte, error) {
@@ -82,6 +82,7 @@ func Sign(key []byte, doc []byte, opts SignatureOptions) ([]byte, error) {
 // ErrVerificationFailed is returned from Verify when the signature is incorrect
 var ErrVerificationFailed = errors.New("signature verification failed")
 
+// values returned from xmlSecDSigCtxVerify
 const (
 	xmlSecDSigStatusUnknown   = 0
 	xmlSecDSigStatusSucceeded = 1
@@ -89,7 +90,7 @@ const (
 )
 
 // Verify checks that the signature in doc is valid according
-// to the XML-DSIG specification. publicKey is the public part of
+// to the XMLDSIG specification. publicKey is the public part of
 // the key used to sign doc. If the signature is not correct,
 // this function returns ErrVerificationFailed.
 func Verify(publicKey []byte, doc []byte, opts SignatureOptions) error {