From 992028394fe1872355469942c81363200626623e Mon Sep 17 00:00:00 2001 From: Oleksandr Redko Date: Thu, 19 Oct 2023 16:21:23 +0300 Subject: [PATCH] Reformat godoc comments according to the latest Go (#867) --- _examples/fileserver/main.go | 21 +++++-------- _examples/limits/main.go | 14 +++------ _examples/logging/main.go | 2 -- _examples/rest/main.go | 40 +++++++++++-------------- _examples/todos-resource/main.go | 4 --- _examples/versions/main.go | 4 --- context.go | 14 ++++----- context_test.go | 16 +++++----- middleware/compress.go | 14 ++++----- middleware/logger.go | 9 +++--- middleware/nocache.go | 9 +++--- middleware/route_headers.go | 51 ++++++++++++++------------------ middleware/timeout.go | 23 +++++++------- middleware/url_format.go | 37 +++++++++++------------ 14 files changed, 115 insertions(+), 143 deletions(-) diff --git a/_examples/fileserver/main.go b/_examples/fileserver/main.go index 06823a35..0df79f86 100644 --- a/_examples/fileserver/main.go +++ b/_examples/fileserver/main.go @@ -1,23 +1,18 @@ -// -// FileServer -// =========== // This example demonstrates how to serve static files from your filesystem. // -// // Boot the server: -// ---------------- -// $ go run main.go +// +// $ go run main.go // // Client requests: -// ---------------- -// $ curl http://localhost:3333/files/ -// 
-// notes.txt
-//
// -// $ curl http://localhost:3333/files/notes.txt -// Notessszzz +// $ curl http://localhost:3333/files/ +// 
+//	notes.txt
+//
// +// $ curl http://localhost:3333/files/notes.txt +// Notessszzz package main import ( diff --git a/_examples/limits/main.go b/_examples/limits/main.go index ddcb2854..08dc729f 100644 --- a/_examples/limits/main.go +++ b/_examples/limits/main.go @@ -1,16 +1,10 @@ -// -// Limits -// ====== // This example demonstrates the use of Timeout, and Throttle middlewares. // -// Timeout: -// cancel a request if processing takes longer than 2.5 seconds, -// server will respond with a http.StatusGatewayTimeout. -// -// Throttle: -// limit the number of in-flight requests along a particular -// routing path and backlog the others. +// Timeout: cancel a request if processing takes longer than 2.5 seconds, +// server will respond with a http.StatusGatewayTimeout. // +// Throttle: limit the number of in-flight requests along a particular +// routing path and backlog the others. package main import ( diff --git a/_examples/logging/main.go b/_examples/logging/main.go index 304e3095..3d090e07 100644 --- a/_examples/logging/main.go +++ b/_examples/logging/main.go @@ -1,5 +1,3 @@ -// Custom Structured Logger -// ======================== // This example demonstrates how to use middleware.RequestLogger, // middleware.LogFormatter and middleware.LogEntry to build a structured // logger using the preview version of the new log/slog package as the logging diff --git a/_examples/rest/main.go b/_examples/rest/main.go index f9c5dcc7..b89ba82c 100644 --- a/_examples/rest/main.go +++ b/_examples/rest/main.go @@ -1,6 +1,3 @@ -// -// REST -// ==== // This example demonstrates a HTTP REST web service with some fixture data. // Follow along the example and patterns. // @@ -8,35 +5,34 @@ // to run yourself do: `go run . -routes` // // Boot the server: -// ---------------- -// $ go run main.go +// +// $ go run main.go // // Client requests: -// ---------------- -// $ curl http://localhost:3333/ -// root. // -// $ curl http://localhost:3333/articles -// [{"id":"1","title":"Hi"},{"id":"2","title":"sup"}] +// $ curl http://localhost:3333/ +// root. // -// $ curl http://localhost:3333/articles/1 -// {"id":"1","title":"Hi"} +// $ curl http://localhost:3333/articles +// [{"id":"1","title":"Hi"},{"id":"2","title":"sup"}] // -// $ curl -X DELETE http://localhost:3333/articles/1 -// {"id":"1","title":"Hi"} +// $ curl http://localhost:3333/articles/1 +// {"id":"1","title":"Hi"} // -// $ curl http://localhost:3333/articles/1 -// "Not Found" +// $ curl -X DELETE http://localhost:3333/articles/1 +// {"id":"1","title":"Hi"} // -// $ curl -X POST -d '{"id":"will-be-omitted","title":"awesomeness"}' http://localhost:3333/articles -// {"id":"97","title":"awesomeness"} +// $ curl http://localhost:3333/articles/1 +// "Not Found" // -// $ curl http://localhost:3333/articles/97 -// {"id":"97","title":"awesomeness"} +// $ curl -X POST -d '{"id":"will-be-omitted","title":"awesomeness"}' http://localhost:3333/articles +// {"id":"97","title":"awesomeness"} // -// $ curl http://localhost:3333/articles -// [{"id":"2","title":"sup"},{"id":"97","title":"awesomeness"}] +// $ curl http://localhost:3333/articles/97 +// {"id":"97","title":"awesomeness"} // +// $ curl http://localhost:3333/articles +// [{"id":"2","title":"sup"},{"id":"97","title":"awesomeness"}] package main import ( diff --git a/_examples/todos-resource/main.go b/_examples/todos-resource/main.go index 2b1b9c57..d2d1d93c 100644 --- a/_examples/todos-resource/main.go +++ b/_examples/todos-resource/main.go @@ -1,11 +1,7 @@ -// -// Todos Resource -// ============== // This example demonstrates a project structure that defines a subrouter and its // handlers on a struct, and mounting them as subrouters to a parent router. // See also _examples/rest for an in-depth example of a REST service, and apply // those same patterns to this structure. -// package main import ( diff --git a/_examples/versions/main.go b/_examples/versions/main.go index 3bd019a0..5b4b192d 100644 --- a/_examples/versions/main.go +++ b/_examples/versions/main.go @@ -1,9 +1,5 @@ -// -// Versions -// ======== // This example demonstrates the use of the render subpackage, with // a quick concept for how to support multiple api versions. -// package main import ( diff --git a/context.go b/context.go index 6aaee8bd..21b1384e 100644 --- a/context.go +++ b/context.go @@ -113,13 +113,13 @@ func (x *Context) URLParam(key string) string { // // For example, // -// func Instrument(next http.Handler) http.Handler { -// return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { -// next.ServeHTTP(w, r) -// routePattern := chi.RouteContext(r.Context()).RoutePattern() -// measure(w, r, routePattern) -// }) -// } +// func Instrument(next http.Handler) http.Handler { +// return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { +// next.ServeHTTP(w, r) +// routePattern := chi.RouteContext(r.Context()).RoutePattern() +// measure(w, r, routePattern) +// }) +// } func (x *Context) RoutePattern() string { routePattern := strings.Join(x.RoutePatterns, "") routePattern = replaceWildcards(routePattern) diff --git a/context_test.go b/context_test.go index 9a254ab8..4731c709 100644 --- a/context_test.go +++ b/context_test.go @@ -6,15 +6,17 @@ import "testing" // If user organizes a router like this: // // (router.go) -// r.Route("/v1", func(r chi.Router) { -// r.Mount("/resources", resourcesController{}.Router()) -// } +// +// r.Route("/v1", func(r chi.Router) { +// r.Mount("/resources", resourcesController{}.Router()) +// } // // (resources_controller.go) -// r.Route("/", func(r chi.Router) { -// r.Get("/{resource_id}", getResource()) -// other routes... -// } +// +// r.Route("/", func(r chi.Router) { +// r.Get("/{resource_id}", getResource()) +// // other routes... +// } // // This test checks how the route pattern is calculated // "/v1/resources/{resource_id}" (right) diff --git a/middleware/compress.go b/middleware/compress.go index faf65a65..28240c4b 100644 --- a/middleware/compress.go +++ b/middleware/compress.go @@ -137,14 +137,14 @@ func NewCompressor(level int, types ...string) *Compressor { // // For example, add the Brotli algorithm: // -// import brotli_enc "gopkg.in/kothar/brotli-go.v0/enc" +// import brotli_enc "gopkg.in/kothar/brotli-go.v0/enc" // -// compressor := middleware.NewCompressor(5, "text/html") -// compressor.SetEncoder("br", func(w io.Writer, level int) io.Writer { -// params := brotli_enc.NewBrotliParams() -// params.SetQuality(level) -// return brotli_enc.NewBrotliWriter(params, w) -// }) +// compressor := middleware.NewCompressor(5, "text/html") +// compressor.SetEncoder("br", func(w io.Writer, level int) io.Writer { +// params := brotli_enc.NewBrotliParams() +// params.SetQuality(level) +// return brotli_enc.NewBrotliWriter(params, w) +// }) func (c *Compressor) SetEncoder(encoding string, fn EncoderFunc) { encoding = strings.ToLower(encoding) if encoding == "" { diff --git a/middleware/logger.go b/middleware/logger.go index 98250d82..cff9bd20 100644 --- a/middleware/logger.go +++ b/middleware/logger.go @@ -31,10 +31,11 @@ var ( // // IMPORTANT NOTE: Logger should go before any other middleware that may change // the response, such as middleware.Recoverer. Example: -// r := chi.NewRouter() -// r.Use(middleware.Logger) // <--<< Logger should come before Recoverer -// r.Use(middleware.Recoverer) -// r.Get("/", handler) +// +// r := chi.NewRouter() +// r.Use(middleware.Logger) // <--<< Logger should come before Recoverer +// r.Use(middleware.Recoverer) +// r.Get("/", handler) func Logger(next http.Handler) http.Handler { return DefaultLogger(next) } diff --git a/middleware/nocache.go b/middleware/nocache.go index 7353448d..9308d40d 100644 --- a/middleware/nocache.go +++ b/middleware/nocache.go @@ -32,10 +32,11 @@ var etagHeaders = []string{ // a router (or subrouter) from being cached by an upstream proxy and/or client. // // As per http://wiki.nginx.org/HttpProxyModule - NoCache sets: -// Expires: Thu, 01 Jan 1970 00:00:00 UTC -// Cache-Control: no-cache, private, max-age=0 -// X-Accel-Expires: 0 -// Pragma: no-cache (for HTTP/1.0 proxies/clients) +// +// Expires: Thu, 01 Jan 1970 00:00:00 UTC +// Cache-Control: no-cache, private, max-age=0 +// X-Accel-Expires: 0 +// Pragma: no-cache (for HTTP/1.0 proxies/clients) func NoCache(h http.Handler) http.Handler { fn := func(w http.ResponseWriter, r *http.Request) { diff --git a/middleware/route_headers.go b/middleware/route_headers.go index dd702956..997bed56 100644 --- a/middleware/route_headers.go +++ b/middleware/route_headers.go @@ -11,39 +11,34 @@ import ( // For example, lets say you'd like to setup multiple routers depending on the // request Host header, you could then do something as so: // -// r := chi.NewRouter() -// rSubdomain := chi.NewRouter() -// -// r.Use(middleware.RouteHeaders(). -// Route("Host", "example.com", middleware.New(r)). -// Route("Host", "*.example.com", middleware.New(rSubdomain)). -// Handler) -// -// r.Get("/", h) -// rSubdomain.Get("/", h2) -// +// r := chi.NewRouter() +// rSubdomain := chi.NewRouter() +// r.Use(middleware.RouteHeaders(). +// Route("Host", "example.com", middleware.New(r)). +// Route("Host", "*.example.com", middleware.New(rSubdomain)). +// Handler) +// r.Get("/", h) +// rSubdomain.Get("/", h2) // // Another example, imagine you want to setup multiple CORS handlers, where for // your origin servers you allow authorized requests, but for third-party public // requests, authorization is disabled. // -// r := chi.NewRouter() -// -// r.Use(middleware.RouteHeaders(). -// Route("Origin", "https://app.skyweaver.net", cors.Handler(cors.Options{ -// AllowedOrigins: []string{"https://api.skyweaver.net"}, -// AllowedMethods: []string{"GET", "POST", "PUT", "DELETE", "OPTIONS"}, -// AllowedHeaders: []string{"Accept", "Authorization", "Content-Type"}, -// AllowCredentials: true, // <----------<<< allow credentials -// })). -// Route("Origin", "*", cors.Handler(cors.Options{ -// AllowedOrigins: []string{"*"}, -// AllowedMethods: []string{"GET", "POST", "PUT", "DELETE", "OPTIONS"}, -// AllowedHeaders: []string{"Accept", "Content-Type"}, -// AllowCredentials: false, // <----------<<< do not allow credentials -// })). -// Handler) -// +// r := chi.NewRouter() +// r.Use(middleware.RouteHeaders(). +// Route("Origin", "https://app.skyweaver.net", cors.Handler(cors.Options{ +// AllowedOrigins: []string{"https://api.skyweaver.net"}, +// AllowedMethods: []string{"GET", "POST", "PUT", "DELETE", "OPTIONS"}, +// AllowedHeaders: []string{"Accept", "Authorization", "Content-Type"}, +// AllowCredentials: true, // <----------<<< allow credentials +// })). +// Route("Origin", "*", cors.Handler(cors.Options{ +// AllowedOrigins: []string{"*"}, +// AllowedMethods: []string{"GET", "POST", "PUT", "DELETE", "OPTIONS"}, +// AllowedHeaders: []string{"Accept", "Content-Type"}, +// AllowCredentials: false, // <----------<<< do not allow credentials +// })). +// Handler) func RouteHeaders() HeaderRouter { return HeaderRouter{} } diff --git a/middleware/timeout.go b/middleware/timeout.go index 8e373536..add596d6 100644 --- a/middleware/timeout.go +++ b/middleware/timeout.go @@ -15,21 +15,20 @@ import ( // // ie. a route/handler may look like: // -// r.Get("/long", func(w http.ResponseWriter, r *http.Request) { -// ctx := r.Context() -// processTime := time.Duration(rand.Intn(4)+1) * time.Second +// r.Get("/long", func(w http.ResponseWriter, r *http.Request) { +// ctx := r.Context() +// processTime := time.Duration(rand.Intn(4)+1) * time.Second // -// select { -// case <-ctx.Done(): -// return +// select { +// case <-ctx.Done(): +// return // -// case <-time.After(processTime): -// // The above channel simulates some hard work. -// } -// -// w.Write([]byte("done")) -// }) +// case <-time.After(processTime): +// // The above channel simulates some hard work. +// } // +// w.Write([]byte("done")) +// }) func Timeout(timeout time.Duration) func(next http.Handler) http.Handler { return func(next http.Handler) http.Handler { fn := func(w http.ResponseWriter, r *http.Request) { diff --git a/middleware/url_format.go b/middleware/url_format.go index 919eb0fe..d8a651e4 100644 --- a/middleware/url_format.go +++ b/middleware/url_format.go @@ -20,30 +20,29 @@ var ( // // Routers should not include a url parameter for the suffix when using this middleware. // -// Sample usage.. for url paths: `/articles/1`, `/articles/1.json` and `/articles/1.xml` +// Sample usage for url paths `/articles/1`, `/articles/1.json` and `/articles/1.xml`: // -// func routes() http.Handler { -// r := chi.NewRouter() -// r.Use(middleware.URLFormat) +// func routes() http.Handler { +// r := chi.NewRouter() +// r.Use(middleware.URLFormat) // -// r.Get("/articles/{id}", ListArticles) +// r.Get("/articles/{id}", ListArticles) // -// return r -// } +// return r +// } // -// func ListArticles(w http.ResponseWriter, r *http.Request) { -// urlFormat, _ := r.Context().Value(middleware.URLFormatCtxKey).(string) -// -// switch urlFormat { -// case "json": -// render.JSON(w, r, articles) -// case "xml:" -// render.XML(w, r, articles) -// default: -// render.JSON(w, r, articles) -// } -// } +// func ListArticles(w http.ResponseWriter, r *http.Request) { +// urlFormat, _ := r.Context().Value(middleware.URLFormatCtxKey).(string) // +// switch urlFormat { +// case "json": +// render.JSON(w, r, articles) +// case "xml:" +// render.XML(w, r, articles) +// default: +// render.JSON(w, r, articles) +// } +// } func URLFormat(next http.Handler) http.Handler { fn := func(w http.ResponseWriter, r *http.Request) { ctx := r.Context()