[ci skip] Update documentation

README.md

@@ -5,13 +5,7 @@
 
 # Go PAM
 
-This is a Go wrapper for the PAM application API. There's not much
+This is a Go wrapper for the PAM application API.
-else to be said. PAM is a simple API and now it's available for use in Go
-applications.
-
-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].
 
 ## Testing
 

example/.gitignore

@@ -1 +0,0 @@
-/example

example_test.go

@@ -1,23 +1,4 @@
-// This is a fake login implementation. It uses whatever default
+package pam_test
-// PAM service configuration is available on the system, and tries
-// to authenticate any user. This should cause PAM to ask its
-// conversation handler for a username and password, in sequence.
-//
-// This application will handle those requests by displaying the
-// PAM-provided prompt and sending back the first line of stdin input
-// it can read for each.
-//
-// Keep in mind that unless run as root (or setuid root), the only
-// user's authentication that can succeed is that of the process owner.
-//
-// It's not a real login for several reasons:
-//
-// It doesn't switch users.
-// It's not a real login.
-//
-// It does however demonstrate a simple but powerful use of PAM.
-
-package main
 
 import (
 	"bufio"
@@ -30,7 +11,17 @@ import (
 	"github.com/msteinert/pam"
 )
 
-func main() {
+// This example uses whatever default PAM service configuration is available
+// on the system, and tries to authenticate any user. This should cause PAM
+// to ask its conversation handler for a username and password, in sequence.
+//
+// This application will handle those requests by displaying the
+// PAM-provided prompt and sending back the first line of stdin input
+// it can read for each.
+//
+// Keep in mind that unless run as root (or setuid root), the only
+// user's authentication that can succeed is that of the process owner.
+func Example_authenticate() {
 	t, err := pam.StartFunc("", "", func(s pam.Style, msg string) (string, error) {
 		switch s {
 		case pam.PromptEchoOff:
@@ -58,5 +49,5 @@ func main() {
 	if err != nil {
 		log.Fatalf("Authenticate: %s", err.Error())
 	}
-	log.Print("Authentication succeeded!")
+	fmt.Println("Authentication succeeded!")
 }

transaction.go

@@ -1,3 +1,4 @@
+// Package pam provides a wrapper for the PAM application API.
 package pam
 
 //#include <security/pam_appl.h>