provide^Wupdate docs of package web

web/error.go

@@ -1,6 +1,6 @@
 package web
 
-// HTTPError as a response, with data
+// HTTPError is returned in HTTP error responses.
 type HTTPError struct {
 	Message string      `json:"message" example:"invalid format"`
 	Error   string      `json:"error,omitempty" example:"<internal error message>"`
@@ -8,10 +8,7 @@ type HTTPError struct {
 }
 
 const (
-	// APIErrorInvalidRequestFormat const for api error with invalid request format
 	APIErrorInvalidRequestFormat = "Invalid Request Format"
-	// APIErrorInternalDatabase const for api error with problem with database
 	APIErrorInternalDatabase     = "Internal Database Error"
-	// APIErrorNotFound const for api error with not found object
 	APIErrorNotFound             = "Not found"
 )

web/main.go

@@ -1,3 +1,12 @@
+/*
+Package web implements common functionality for web APIs using Gin and Gorm.
+
+Modules
+
+Modules provide functionality for a web server. A module is a function executed
+before starting a server, accessing the Service and the Gin Engine. Each Service
+maintains a list of modules. When it runs, it executes all of its modules.
+*/
 package web
 
 import (
@@ -13,8 +22,7 @@ import (
 	"gorm.io/gorm"
 )
 
-// Service to store Configuration and Webserver wide objects
-// (like DB Connection)
+// A Service stores configuration of a server.
 type Service struct {
 	// config
 	Listen    string `toml:"listen"`
@@ -36,32 +44,32 @@ type Service struct {
 	modules []ModuleRegisterFunc
 }
 
-// Run to startup all related web parts
-// (e.g. configure the server, metrics, and finally bind routing)
-func (config *Service) Run() error {
+// Run creates, configures, and runs a new gin.Engine using its registered
+// modules.
+func (s *Service) Run() error {
 	gin.EnableJsonDecoderDisallowUnknownFields()
 	gin.SetMode(gin.ReleaseMode)
 	r := gin.New()
 	// catch crashed
 	r.Use(gin.Recovery())
 
-	if config.AccessLog {
+	if s.AccessLog {
 		r.Use(gin.Logger())
 		log.Debug("request logging enabled")
 	}
-	config.LoadSession(r)
-	config.Bind(r)
+	s.LoadSession(r)
+	s.Bind(r)
 
-	if config.ACME.Enable {
-		if config.Listen != "" {
+	if s.ACME.Enable {
+		if s.Listen != "" {
 			log.Panic("For ACME / Let's Encrypt it is not possible to set `listen`")
 		}
 		m := autocert.Manager{
 			Prompt:     autocert.AcceptTOS,
-			HostPolicy: autocert.HostWhitelist(config.ACME.Domains...),
-			Cache:      autocert.DirCache(config.ACME.Cache),
+			HostPolicy: autocert.HostWhitelist(s.ACME.Domains...),
+			Cache:      autocert.DirCache(s.ACME.Cache),
 		}
 		return autotls.RunWithManager(r, &m)
 	}
-	return r.Run(config.Listen)
+	return r.Run(s.Listen)
 }

web/module.go

@@ -6,15 +6,15 @@ import (
 	"github.com/gin-gonic/gin"
 )
 
-// ModuleRegisterFunc format of module which registered to WebService
+// A ModuleRegisterFunc is a module.
 type ModuleRegisterFunc func(*gin.Engine, *Service)
 
-// ModuleRegister used on start of WebService
+// ModuleRegister adds f to ws's list of modules.
 func (ws *Service) ModuleRegister(f ModuleRegisterFunc) {
 	ws.modules = append(ws.modules, f)
 }
 
-// Bind WebService to gin.Engine
+// Bind executes all of ws's modules with r.
 func (ws *Service) Bind(r *gin.Engine) {
 	for _, f := range ws.modules {
 		f(r, ws)

web/request.go

@@ -6,9 +6,11 @@ import (
 	"time"
 )
 
-// JSONRequest easy get request for json
+// JSONRequest issues a GET request to the specified URL and reads the returned
+// JSON into value. See json.Unmarshal for the rules for converting JSON into a
+// value.
 func JSONRequest(url string, value interface{}) error {
-	var netClient = &http.Client{
+	netClient := &http.Client{
 		Timeout: time.Second * 20,
 	}
 
@@ -18,6 +20,7 @@ func JSONRequest(url string, value interface{}) error {
 	}
 
 	err = json.NewDecoder(resp.Body).Decode(&value)
+	resp.Body.Close()
 	if err != nil {
 		return err
 	}

web/response.go

@@ -5,19 +5,21 @@ import (
 )
 
 const (
-	// ContentTypeJSON content type of json
 	ContentTypeJSON = "application/json"
-	// ContentTypeJS content type of javascript
 	ContentTypeJS   = "application/javascript"
-	// ContentTypeXML content type of xml
 	ContentTypeXML  = "text/xml"
-	// ContentTypeYAML content type of yaml
 	ContentTypeYAML = "text/yaml"
-	// ContentTypeHTML content type of html
 	ContentTypeHTML = "text/html"
 )
 
-// Response give
+// Response sends an HTTP response.
+//
+// statusCode is the respone's status.
+//
+// If the request's Content-Type is JavaScript, JSON, YAML, or XML, it returns
+// data serialized as JSONP, JSON, YAML, or XML, respectively. If the
+// Content-Type is HTML, it returns the HTML template templateName rendered with
+// data.
 func Response(ctx *gin.Context, statusCode int, data interface{}, templateName string) {
 	switch ctx.ContentType() {
 	case ContentTypeJS:

web/session.go

@@ -6,8 +6,8 @@ import (
 	"github.com/gin-gonic/gin"
 )
 
-// LoadSession module to start Session Handling in WebService
-func (config *Service) LoadSession(r *gin.Engine) {
-	store := cookie.NewStore([]byte(config.Session.Secret))
-	r.Use(sessions.Sessions(config.Session.Name, store))
+// LoadSessions starts session handling for s.
+func (s *Service) LoadSession(r *gin.Engine) {
+	store := cookie.NewStore([]byte(s.Session.Secret))
+	r.Use(sessions.Sessions(s.Session.Name, store))
 }