diff --git a/client.go b/client.go
index 6b10ff5..f939511 100644
--- a/client.go
+++ b/client.go
@@ -51,7 +51,13 @@ type Client struct {
 
 	// TrustCertificate is called to determine whether the client
 	// should trust a certificate it has not seen before.
-	// If TrustCertificate is nil, the certificate will not be trusted.
+	// If TrustCertificate is nil, the certificate will not be trusted
+	// and the connection will be aborted.
+	//
+	// If TrustCertificate returns TrustOnce, the certificate will be added
+	// to the client's list of known hosts.
+	// If TrustCertificate returns TrustAlways, the certificate will also be
+	// written to the known hosts file.
 	TrustCertificate func(hostname string, cert *x509.Certificate) Trust
 }
 
diff --git a/doc.go b/doc.go
index 76306d0..0fae695 100644
--- a/doc.go
+++ b/doc.go
@@ -37,8 +37,8 @@ Clients can load their own list of known hosts:
 
 Clients can control when to trust certificates with TrustCertificate:
 
-	client.TrustCertificate = func(hostname string, cert *x509.Certificate, knownHosts *gemini.KnownHosts) error {
-		return knownHosts.Lookup(hostname, cert)
+	client.TrustCertificate = func(hostname string, cert *x509.Certificate) gemini.Trust {
+		return gemini.TrustOnce
 	}
 
 Clients can create client certificates upon the request of a server:
@@ -53,7 +53,7 @@ Server is a Gemini server.
 
 	var server gemini.Server
 
-Servers must be configured with certificates:
+Servers should be configured with certificates:
 
 	err := server.Certificates.Load("/var/lib/gemini/certs")
 	if err != nil {