Documentation improvements

Author: ecnepsnai

api.go

@@ -13,7 +13,7 @@ import (
 )
 
 // API describes a JSON API server. API handles return data or an error, and all responses are wrapped in a common
-// response object.
+// response object; [web.JSONResponse].
 type API struct {
 	server *Server
 }

go.mod

@@ -5,5 +5,5 @@ go 1.19
 require (
 	github.com/ecnepsnai/logtic v1.9.5
 	github.com/gorilla/websocket v1.5.3
-	golang.org/x/time v0.7.0
+	golang.org/x/time v0.8.0
 )

go.sum

@@ -2,7 +2,5 @@ github.com/ecnepsnai/logtic v1.9.5 h1:p1IAUPGHNve0597vChLHGYFPXx1qR3+y66yIZefdvl
 github.com/ecnepsnai/logtic v1.9.5/go.mod h1:fs2kkqGqiX77ejVNBKpSV/dMVtn9bTg9YtHLP9MC0U8=
 github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aNNg=
 github.com/gorilla/websocket v1.5.3/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
-golang.org/x/time v0.6.0 h1:eTDhh4ZXt5Qf0augr54TN6suAUudPcawVZeIAPU7D4U=
-golang.org/x/time v0.6.0/go.mod h1:3BpzKBy/shNhVucY/MWOyx10tF3SFh9QdLuxbVysPQM=
-golang.org/x/time v0.7.0 h1:ntUhktv3OPE6TgYxXWv9vKvUSJyIFJlyohwbkEwPrKQ=
-golang.org/x/time v0.7.0/go.mod h1:3BpzKBy/shNhVucY/MWOyx10tF3SFh9QdLuxbVysPQM=
+golang.org/x/time v0.8.0 h1:9i3RxcPv3PZnitoVGMPDKZSq1xW1gK1Xy3ArNOGZfEg=
+golang.org/x/time v0.8.0/go.mod h1:3BpzKBy/shNhVucY/MWOyx10tF3SFh9QdLuxbVysPQM=

handle.go

@@ -19,28 +19,28 @@ type SocketHandle func(request Request, conn *WSConn)
 
 // HandleOptions describes options for a route
 type HandleOptions struct {
-	// AuthenticateMethod method called to determine if a request is properly authenticated or not.
-	// Optional - Omit this entirely if no authentication is needed for the request.
-	// Return nil to signal an unauthenticated request, which will be rejected.
-	// Objects returned will be passed to the handle as the UserData object.
+	// AuthenticateMethod method called to determine if a request is properly authenticated or not. If a method is
+	// provided, then it is called for each incoming request. The value returned by this method is passed as the
+	// UserData field of a [web.Request]. Returning nil signals an unauthenticated request, which will be handled by
+	// the UnauthorizedMethod (if provided) or a default handle. If the AuthenticateMethod is not provided, then the
+	// UserData field is nil.
 	AuthenticateMethod func(request *http.Request) interface{}
 	// PreHandle is an optional method that is called immediately upon receiving the HTTP request, before authentication
 	// and before rate limit checks. This method allows servers to provide early handling of a request before any
 	// processing happens.
 	//
-	// The value of the error is not used, only if an error or nil was returned. If an error is returned then no more
-	// processing is performed. It is assumed that a response will have been written to w.
+	// The returned error is only used as a nil check, the value of any error isn't used. If an error is returned then
+	// no more processing is performed. It is assumed that a response will have been written to w.
 	//
 	// If nil is returned then the request will continue normally, no status should have been written to w. Any headers
 	// added may be overwritten by the handle.
 	PreHandle func(w http.ResponseWriter, request *http.Request) error
-	// UnauthorizedMethod method called when an unauthenticated request occurs (AuthenticateMethod returned nil)
-	// to customize the response seen by the user.
-	// Optional - Omit this to have a default response.
+	// UnauthorizedMethod method called when an unauthenticated request occurs, i.e.AuthenticateMethod returned nil,
+	// which allows you to customize the response seen by the user.
+	// If omitted, a default handle is used.
 	UnauthorizedMethod func(w http.ResponseWriter, request *http.Request)
-	// MaxBodyLength defines the maximum length accepted for any HTTP request body. Requests that
-	// exceed this limit will receive a 413 Payload Too Large response.
-	// The default value of 0 will not reject requests with large bodies.
+	// MaxBodyLength defines the maximum length accepted for any HTTP request body. Requests that exceed this limit will
+	// receive a "413 Payload Too Large" response. The default value of 0 will not reject requests with large bodies.
 	MaxBodyLength uint64
 	// DontLogRequests if true then requests to this handle are not logged
 	DontLogRequests bool

http_easy.go

@@ -12,11 +12,14 @@ import (
 	"github.com/ecnepsnai/web/router"
 )
 
-// HTTPEasy describes a HTTPEasy server. HTTPEasy handles are expected to return a reader and specify the content
-// type and length themselves.
+// HTTPEasy describes a simple to use HTTP router. HTTPEasy handles are expected to return a reader and specify the
+// content type and length themselves.
 //
-// The HTTPEasy server supports HTTPEasy range requests, should the client request it and the application provide a
-// supported Reader (io.ReadSeekCloser).
+// HTTP abstracts many features away from the caller, providing a simpler experience when a only a simple HTTP server
+// is needed. If you require more control, use the HTTP router.
+//
+// The HTTPEasy server supports HTTP range requests, should the client request it and the application provide a
+// supported Reader [io.ReadSeekCloser].
 type HTTPEasy struct {
 	server *Server
 }

request.go

@@ -21,7 +21,11 @@ type Decoder interface {
 	Decode(v any) error
 }
 
-// DecodeJSON unmarshal the JSON body to the provided interface
+// DecodeJSON unmarshal the JSON body to the provided interface.
+//
+// Equal to calling:
+//
+//	r.Decode(v, json.NewDecoder(r.HTTP.Body))
 func (r Request) DecodeJSON(v any) *Error {
 	return r.Decode(v, json.NewDecoder(r.HTTP.Body))
 }
@@ -41,6 +45,8 @@ func (r Request) Decode(v any, decoder Decoder) *Error {
 // RealRemoteAddr will try to get the real IP address of the incoming connection taking proxies into
 // consideration. This function looks for the `X-Real-IP`, `X-Forwarded-For`, and `CF-Connecting-IP`
 // headers, and if those don't exist will return the remote address of the connection.
+//
+// Will never return nil, if it is unable to get a valid address it will return 0.0.0.0
 func (r Request) RealRemoteAddr() net.IP {
 	return RealRemoteAddr(r.HTTP)
 }

response.go

@@ -35,6 +35,6 @@ type HTTPResponse struct {
 	Cookies []http.Cookie
 	// The content type of the response. Will overwrite any 'content-type' header in Headers.
 	ContentType string
-	// The length of the content.
+	// The length of the content. Will overwrite any 'content-length' header in Headers.
 	ContentLength uint64
 }

server.go

@@ -18,13 +18,13 @@ type Server struct {
 	// The port that this server is listening on. Only populated if the server was created with web.New().
 	ListenPort uint16
 	// The JSON API server. API handles return data or an error, and all responses are wrapped in a common
-	// response object.
+	// response object; [web.JSONResponse].
 	API API
 	// HTTPEasy describes a easy HTTP server. HTTPEasy handles are expected to return a reader and specify the content
 	// type and length themselves.
 	//
 	// The HTTPEasy server supports HTTP range requests, should the client request it and the application provide a
-	// supported Reader (io.ReadSeekCloser).
+	// supported Reader [io.ReadSeekCloser].
 	HTTPEasy HTTPEasy
 	// The HTTP server. HTTP handles are exposed to the raw http request and response writers.
 	HTTP HTTP

util.go

@@ -8,6 +8,8 @@ import (
 // RealRemoteAddr will try to get the real IP address of the incoming connection taking proxies into
 // consideration. This function looks for the `X-Real-IP`, `X-Forwarded-For`, and `CF-Connecting-IP`
 // headers, and if those don't exist will return the remote address of the connection.
+//
+// Will never return nil, if it is unable to get a valid address it will return 0.0.0.0
 func RealRemoteAddr(r *http.Request) net.IP {
 	if ip := net.ParseIP(r.Header.Get("X-Real-IP")); ip != nil {
 		return ip

web.go

@@ -1,11 +1,62 @@
 /*
-Package web is a HTTP server for Golang applications.
+Package web is a full-featured HTTP router and server for Go applications, suitable for serving static files, REST APIs,
+and more.
 
-It is suitable for both front-end and back-end use, being able to deliver static content, act as a REST-ful JSON server,
-and as a WebSocket server.
+Web includes these features:
+  - HTTP range support
+  - Static file serving
+  - Directory listings
+  - Websockets
+  - Per-IP rate limiting
+  - Per-request contextual data
 
-It includes simple controls to allow for user authentication with contextual data being available in every request, and
-provides simple per-user rate-limiting.
+Web offers four APIs for developers to choose from:
+
+# API
+
+API provides everything you need to build poweful REST APIs using JSON. Define your routes and easily accept and return
+data as JSON.
+
+Example:
+
+	router := web.New("[::]:8080")
+	router.API.Get("/users", getUsers, options)
+	router.API.Get("/users/:username", getUsers, options)
+
+For more information, see the documentation of [web.API].
+
+# HTTPEasy
+
+HTTPEasy provides a straightforward interface to accept HTTP requets and return data.
+
+Example:
+
+	router := web.New("[::]:8080")
+	router.HTTPEasy.Get("/index.html", getIndex, options)
+	router.HTTPEasy.Get("/cat.jpg", getKitty, options)
+
+For more information, see the documentation of [web.HTTPEasy].
+
+# HTTP
+
+HTTP provides full access to the original HTTP request, allowing you total control over the response, whatever that may be.
+
+Example:
+
+	router := web.New("[::]:8080")
+	router.HTTP.Get("/index.html", getIndex, options)
+	router.HTTP.Get("/cat.jpg", getKitty, options)
+
+For more information, see the documentation of [web.HTTP].
+
+# Websockets
+
+This package also provides a wrapper for [github.com/gorilla/websocket]
+
+Example:
+
+	router := web.New("[::]:8080")
+	router.Socket("/ws", handleSocket, options)
 */
 package web