Update documentation

client.go

@@ -15,10 +15,10 @@ import (
 
 // A Client is a Gemini client. Its zero value is a usable client.
 type Client struct {
-	// TrustCertificate is called to determine whether the client
-	// should trust the certificate provided by the server.
-	// If TrustCertificate is nil, the client will accept any certificate.
-	// If the returned error is not nil, the certificate will not be trusted
+	// TrustCertificate is called to determine whether the client should
+	// trust the certificate provided by the server.
+	// If TrustCertificate is nil or returns nil, the client will accept
+	// any certificate. Otherwise, the certificate will not be trusted
 	// and the request will be aborted.
 	//
 	// See the tofu submodule for an implementation of trust on first use.
@@ -36,8 +36,7 @@ type Client struct {
 // An error is returned if there was a Gemini protocol error.
 // A non-2x status code doesn't cause an error.
 //
-// If the returned error is nil, the Response will contain a non-nil Body
-// which the user is expected to close.
+// If the returned error is nil, the user is expected to close the Response.
 //
 // For more control over requests, use NewRequest and Client.Do.
 func (c *Client) Get(ctx context.Context, url string) (*Response, error) {
@@ -55,8 +54,7 @@ func (c *Client) Get(ctx context.Context, url string) (*Response, error) {
 // An error is returned if there was a Gemini protocol error.
 // A non-2x status code doesn't cause an error.
 //
-// If the returned error is nil, the Response will contain a non-nil Body
-// which the user is expected to close.
+// If the returned error is nil, the user is expected to close the Response.
 //
 // Generally Get will be used instead of Do.
 func (c *Client) Do(ctx context.Context, req *Request) (*Response, error) {

fs.go

@@ -65,8 +65,8 @@ func serveContent(w ResponseWriter, name string, content io.Reader) {
 //
 // As a precaution, ServeFile will reject requests where r.URL.Path contains a
 // ".." path element; this protects against callers who might unsafely use
-// filepath.Join on r.URL.Path without sanitizing it and then use that
-// filepath.Join result as the name argument.
+// path.Join on r.URL.Path without sanitizing it and then use that
+// path.Join result as the name argument.
 //
 // As another special case, ServeFile redirects any request where r.URL.Path
 // ends in "/index.gmi" to the same path, without the final "index.gmi". To
@@ -81,7 +81,7 @@ func ServeFile(w ResponseWriter, r *Request, fsys fs.FS, name string) {
 		// serveFile. Reject the request under the assumption that happened
 		// here and ".." may not be wanted.
 		// Note that name might not contain "..", for example if code (still
-		// incorrectly) used filepath.Join(myDir, r.URL.Path).
+		// incorrectly) used path.Join(myDir, r.URL.Path).
 		w.WriteHeader(StatusBadRequest, "invalid URL path")
 		return
 	}

query.go

@@ -12,7 +12,8 @@ func QueryEscape(query string) string {
 	return strings.ReplaceAll(url.PathEscape(query), "+", "%2B")
 }
 
-// QueryUnescape is identical to url.PathUnescape.
+// QueryUnescape unescapes a Gemini URL query.
+// It is identical to url.PathUnescape.
 func QueryUnescape(query string) (string, error) {
 	return url.PathUnescape(query)
 }

request.go

@@ -10,11 +10,8 @@ import (
 
 // A Request represents a Gemini request received by a server or to be sent
 // by a client.
-//
-// The field semantics differ slightly between client and server usage.
 type Request struct {
-	// URL specifies the URL being requested (for server
-	// requests) or the URL to access (for client requests).
+	// URL specifies the URL being requested.
 	URL *url.URL
 
 	// For client requests, Host optionally specifies the server to
@@ -23,6 +20,7 @@ type Request struct {
 	// For international domain names, Host may be in Punycode or
 	// Unicode form. Use golang.org/x/net/idna to convert it to
 	// either format if needed.
+	// This field is ignored by the Gemini server.
 	Host string
 
 	// For client requests, Certificate optionally specifies the
@@ -34,7 +32,6 @@ type Request struct {
 }
 
 // NewRequest returns a new request.
-//
 // The returned Request is suitable for use with Client.Do.
 //
 // Callers should be careful that the URL query is properly escaped.

response.go

@@ -202,7 +202,7 @@ type responseWriter struct {
 	bodyAllowed bool
 }
 
-// NewResponseWriter returns a ResponseWriter that uses the provided io.Writer.
+// NewResponseWriter returns a ResponseWriter that uses the provided io.WriteCloser.
 func NewResponseWriter(wc io.WriteCloser) ResponseWriter {
 	return newResponseWriter(wc)
 }
@@ -253,7 +253,7 @@ func (w *responseWriter) Flush() error {
 	if !w.wroteHeader {
 		w.WriteHeader(StatusTemporaryFailure, "Temporary failure")
 	}
-	// Write errors from writeHeader will be returned here.
+	// Write errors from WriteHeader will be returned here.
 	return w.b.Flush()
 }
 

server.go

@@ -229,8 +229,8 @@ func (srv *Server) deleteListener(l *net.Listener) {
 }
 
 // Serve accepts incoming connections on the Listener l, creating a new
-// service goroutine for each. The service goroutines reads the request and
-// then calls the appropriate Handler to reply to them. If the provided
+// service goroutine for each. The service goroutines read the requests and
+// then call the appropriate Handler to reply to them. If the provided
 // context expires, Serve closes l and returns the context's error.
 //
 // Serve always closes l and returns a non-nil error.