From 064bef37e784c7bd0f30b56d947fc82ded189ba7 Mon Sep 17 00:00:00 2001
From: Ross Kinder <ross@kndr.org>
Date: Wed, 23 Dec 2015 14:44:38 -0500
Subject: [PATCH] cleanup: add/fix comments

---
 error.go         | 7 +++++--
 error_thunk.go   | 6 ++++--
 thread_darwin.go | 3 +++
 thread_linux.go  | 1 +
 xmldsig.go       | 5 +++--
 5 files changed, 16 insertions(+), 6 deletions(-)

diff --git a/error.go b/error.go
index 3611b89..dfce98f 100644
--- a/error.go
+++ b/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()
diff --git a/error_thunk.go b/error_thunk.go
index dec27a6..d6211a4 100644
--- a/error_thunk.go
+++ b/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);
diff --git a/thread_darwin.go b/thread_darwin.go
index 79f4c66..c1f122b 100644
--- a/thread_darwin.go
+++ b/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()))
 }
diff --git a/thread_linux.go b/thread_linux.go
index 20f2d4c..a544fbd 100644
--- a/thread_linux.go
+++ b/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())
 }
diff --git a/xmldsig.go b/xmldsig.go
index e8dabd8..3fbb012 100644
--- a/xmldsig.go
+++ b/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 {