Update documentation

This commit is contained in:
Adnan Maolood 2021-02-23 18:45:58 -05:00
parent 5cf936d304
commit 02bbedc330
6 changed files with 17 additions and 21 deletions

View File

@ -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) {

6
fs.go
View File

@ -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
}

View File

@ -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)
}

View File

@ -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.

View File

@ -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()
}

View File

@ -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.