Small documentation updates

README.md

@@ -11,8 +11,11 @@ There's an example of a "fake login" program in the examples directory.
 Look at the pam module's [godocs][1] for details about the Go API, or refer
 to the official [PAM documentation][2].
 
-The test suite must be run as the root user. To setup your system for testing,
-create a user named "test" with the password "secret". For example:
+## Testing
+
+To run the full suite, the tests must be run as the root user. To setup your
+system for testing, create a user named "test" with the password "secret". For
+example:
 
 ```
 $ sudo useradd test \
@@ -21,5 +24,11 @@ $ sudo useradd test \
     -s /bin/false
 ```
 
+Then execute the tests:
+
+```
+$ sudo GOPATH=$GOPATH $(which go) test -v
+```
+
 [1]: http://godoc.org/github.com/msteinert/pam
 [2]: http://www.kernel.org/pub/linux/libs/pam/Linux-PAM-html/adg-interface-by-app-expected.html

transaction.go

@@ -45,7 +45,7 @@ type Conversation struct {
 }
 
 // Constructs a new conversation object with a given handler and a newly
-// allocated pam_conv struct that uses this object as its appdata_ptr
+// allocated pam_conv struct that uses this object as its appdata_ptr.
 func NewConversation(handler ConversationHandler) (*Conversation, C.int) {
 	c := &Conversation{}
 	c.handler = handler
@@ -82,14 +82,11 @@ func TransactionFinalizer(t *Transaction) {
 	C.free(unsafe.Pointer(t.conv.conv))
 }
 
-// Start initiates a new PAM transaction. service is treated identically
+// Start initiates a new PAM transaction. Service is treated identically
 // to how pam_start treats it internally.
 //
 // All application calls to PAM begin with Start(). The returned *Transaction
 // provides an interface to the remainder of the API.
-//
-// The returned status int may be ABORT, BUF_ERR, SUCCESS, or SYSTEM_ERR, as per
-// the official PAM documentation.
 func Start(service, user string, handler ConversationHandler) (*Transaction, error) {
 	t := &Transaction{}
 	t.conv, t.status = NewConversation(handler)