docs: update funcs documentation with go 1.19 doc standards (#499)

Author: morremeyer

.golangci.yml

@@ -30,13 +30,8 @@ linters:
   enable:
     - gocyclo
     - godot
-    # Disabled as the latest version - 0.4.0 from 2022-09-27 is not built with go 1.19 and
-    # therefore disagrees with swag fmt about the formatting of the swagger comments.
-    # See https://github.com/mvdan/gofumpt/issues/254
-    # - gofumpt
-
-    # Disabled since goimports reformats correct 1.19 doc comments
-    # - goimports
+    - gofumpt
+    - goimports
     - govet
     - revive
     - whitespace
@@ -50,4 +45,4 @@ linters-settings:
 
   godot:
     exclude:
-      - "^ @[A-Za-z]+ "
+      - "^\t+@[A-Za-z]+\t+"

pkg/controllers/account.go

@@ -71,6 +71,8 @@ func (co Controller) RegisterAccountRoutes(r *gin.RouterGroup) {
 	}
 }
 
+// OptionsAccountList returns the allowed HTTP verbs
+//
 //	@Summary		Allowed HTTP verbs
 //	@Description	Returns an empty response with the HTTP Header "allow" set to the allowed HTTP verbs
 //	@Tags			Accounts
@@ -82,6 +84,8 @@ func (co Controller) OptionsAccountList(c *gin.Context) {
 	httputil.OptionsGetPost(c)
 }
 
+// OptionsAccountDetail returns the allowed HTTP verbs
+//
 //	@Summary		Allowed HTTP verbs
 //	@Description	Returns an empty response with the HTTP Header "allow" set to the allowed HTTP verbs
 //	@Tags			Accounts
@@ -104,6 +108,8 @@ func (co Controller) OptionsAccountDetail(c *gin.Context) {
 	httputil.OptionsGetPatchDelete(c)
 }
 
+// CreateAccount creates a new account
+//
 //	@Summary		Create account
 //	@Description	Creates a new account
 //	@Tags			Accounts
@@ -135,6 +141,8 @@ func (co Controller) CreateAccount(c *gin.Context) {
 	c.JSON(http.StatusCreated, AccountResponse{Data: accountObject})
 }
 
+// GetAccounts returns a list of all accounts matching the filter parameters
+//
 //	@Summary		List accounts
 //	@Description	Returns a list of accounts
 //	@Tags			Accounts
@@ -185,6 +193,8 @@ func (co Controller) GetAccounts(c *gin.Context) {
 	c.JSON(http.StatusOK, AccountListResponse{Data: accountObjects})
 }
 
+// GetAccount returns data for a specific account
+//
 //	@Summary		Get account
 //	@Description	Returns a specific account
 //	@Tags			Accounts
@@ -210,6 +220,8 @@ func (co Controller) GetAccount(c *gin.Context) {
 	c.JSON(http.StatusOK, AccountResponse{Data: accountObject})
 }
 
+// UpdateAccount updates data for a specific account
+//
 //	@Summary		Update account
 //	@Description	Updates an account. Only values to be updated need to be specified.
 //	@Tags			Accounts
@@ -251,6 +263,8 @@ func (co Controller) UpdateAccount(c *gin.Context) {
 	c.JSON(http.StatusOK, AccountResponse{Data: accountObject})
 }
 
+// DeleteAccount deletes an account
+//
 //	@Summary		Delete account
 //	@Description	Deletes an account
 //	@Tags			Accounts

pkg/controllers/allocation.go

@@ -69,6 +69,8 @@ func (co Controller) RegisterAllocationRoutes(r *gin.RouterGroup) {
 	}
 }
 
+// OptionsAllocationList returns the allowed HTTP verbs
+//
 //	@Summary		Allowed HTTP verbs
 //	@Description	Returns an empty response with the HTTP Header "allow" set to the allowed HTTP verbs
 //	@Tags			Allocations
@@ -78,6 +80,8 @@ func (co Controller) OptionsAllocationList(c *gin.Context) {
 	httputil.OptionsGetPost(c)
 }
 
+// OptionsAllocationDetail returns the allowed HTTP verbs
+//
 //	@Summary		Allowed HTTP verbs
 //	@Description	Returns an empty response with the HTTP Header "allow" set to the allowed HTTP verbs
 //	@Tags			Allocations
@@ -98,6 +102,8 @@ func (co Controller) OptionsAllocationDetail(c *gin.Context) {
 	httputil.OptionsGetPatchDelete(c)
 }
 
+// CreateAllocation creates a new allocation
+//
 //	@Summary		Create allocations
 //	@Description	Create a new allocation of funds to an envelope for a specific month
 //	@Tags			Allocations
@@ -132,6 +138,8 @@ func (co Controller) CreateAllocation(c *gin.Context) {
 	c.JSON(http.StatusCreated, AllocationResponse{Data: allocationObject})
 }
 
+// GetAllocations returns a list of allocations matching the search parameters
+//
 //	@Summary		Get allocations
 //	@Description	Returns a list of allocations
 //	@Tags			Allocations
@@ -180,6 +188,8 @@ func (co Controller) GetAllocations(c *gin.Context) {
 	c.JSON(http.StatusOK, AllocationListResponse{Data: allocationObjects})
 }
 
+// GetAllocation returns data about a specific allocation
+//
 //	@Summary		Get allocation
 //	@Description	Returns a specific allocation
 //	@Tags			Allocations
@@ -205,6 +215,8 @@ func (co Controller) GetAllocation(c *gin.Context) {
 	c.JSON(http.StatusOK, AllocationResponse{Data: allocationObject})
 }
 
+// UpdateAllocation updates allocation data
+//
 //	@Summary		Update allocation
 //	@Description	Update an allocation. Only values to be updated need to be specified.
 //	@Tags			Allocations
@@ -250,6 +262,8 @@ func (co Controller) UpdateAllocation(c *gin.Context) {
 	c.JSON(http.StatusOK, AllocationResponse{Data: allocationObject})
 }
 
+// DeleteAllocation deletes an allocation
+//
 //	@Summary		Delete allocation
 //	@Description	Deletes an allocation
 //	@Tags			Allocations

pkg/controllers/budget.go

@@ -83,6 +83,8 @@ func (co Controller) RegisterBudgetRoutes(r *gin.RouterGroup) {
 	}
 }
 
+// OptionsBudgetList returns the allowed HTTP methods
+//
 //	@Summary		Allowed HTTP verbs
 //	@Description	Returns an empty response with the HTTP Header "allow" set to the allowed HTTP verbs
 //	@Tags			Budgets
@@ -93,6 +95,8 @@ func (co Controller) OptionsBudgetList(c *gin.Context) {
 	httputil.OptionsGetPost(c)
 }
 
+// OptionsBudgetDetail returns the allowed HTTP methods
+//
 //	@Summary		Allowed HTTP verbs
 //	@Description	Returns an empty response with the HTTP Header "allow" set to the allowed HTTP verbs
 //	@Tags			Budgets
@@ -116,6 +120,8 @@ func (co Controller) OptionsBudgetDetail(c *gin.Context) {
 	httputil.OptionsGetPatchDelete(c)
 }
 
+// OptionsBudgetMonth returns the allowed HTTP methods
+//
 //	@Summary		Allowed HTTP verbs
 //	@Description	Returns an empty response with the HTTP Header "allow" set to the allowed HTTP verbs. **Use OPTIONS /month endpoint with month and budgetId query parameters instead.**
 //	@Tags			Budgets
@@ -147,6 +153,8 @@ func (co Controller) OptionsBudgetMonth(c *gin.Context) {
 	httputil.OptionsGet(c)
 }
 
+// OptionsBudgetMonthAllocations returns the allowed HTTP methods
+//
 //	@Summary		Allowed HTTP verbs
 //	@Description	Returns an empty response with the HTTP Header "allow" set to the allowed HTTP verbs. **Use OPTIONS /month endpoint with month and budgetId query parameters instead.**
 //	@Tags			Budgets
@@ -179,6 +187,8 @@ func (co Controller) OptionsBudgetMonthAllocations(c *gin.Context) {
 	httputil.OptionsDelete(c)
 }
 
+// CreateBudget creates a new budget
+//
 //	@Summary		Create budget
 //	@Description	Creates a new budget
 //	@Tags			Budgets
@@ -208,6 +218,8 @@ func (co Controller) CreateBudget(c *gin.Context) {
 	c.JSON(http.StatusCreated, BudgetResponse{Data: budgetObject})
 }
 
+// GetBudgets returns data for all budgets filtered by the query parameters
+//
 //	@Summary		List budgets
 //	@Description	Returns a list of budgets
 //	@Tags			Budgets
@@ -252,6 +264,8 @@ func (co Controller) GetBudgets(c *gin.Context) {
 	c.JSON(http.StatusOK, BudgetListResponse{Data: budgetObjects})
 }
 
+// GetBudget returns data for a single budget
+//
 //	@Summary		Get budget
 //	@Description	Returns a specific budget
 //	@Tags			Budgets
@@ -277,6 +291,8 @@ func (co Controller) GetBudget(c *gin.Context) {
 	c.JSON(http.StatusOK, BudgetResponse{Data: budgetObject})
 }
 
+// GetBudgetMonth returns data for a month for a specific budget
+//
 //	@Summary		Get Budget month data
 //	@Description	Returns data about a budget for a for a specific month. **Use GET /month endpoint with month and budgetId query parameters instead.**
 //	@Tags			Budgets
@@ -391,6 +407,8 @@ func (co Controller) GetBudgetMonth(c *gin.Context) {
 	}})
 }
 
+// UpdateBudget updates data for a budget
+//
 //	@Summary		Update budget
 //	@Description	Update an existing budget. Only values to be updated need to be specified.
 //	@Tags			Budgets
@@ -437,6 +455,8 @@ func (co Controller) UpdateBudget(c *gin.Context) {
 	c.JSON(http.StatusOK, BudgetResponse{Data: budgetObject})
 }
 
+// Do stuff
+//
 //	@Summary		Delete budget
 //	@Description	Deletes a budget
 //	@Tags			Budgets
@@ -465,6 +485,8 @@ func (co Controller) DeleteBudget(c *gin.Context) {
 	c.JSON(http.StatusNoContent, gin.H{})
 }
 
+// DeleteAllocationsMonth deletes all allocations for a specific month
+//
 //	@Summary		Delete allocations for a month
 //	@Description	Deletes all allocation for the specified month. **Use DELETE /month endpoint with month and budgetId query parameters instead.**
 //	@Tags			Budgets
@@ -520,6 +542,8 @@ func (co Controller) DeleteAllocationsMonth(c *gin.Context) {
 	c.JSON(http.StatusNoContent, gin.H{})
 }
 
+// SetAllocationsMonth sets all allocations for a specific month
+//
 //	@Summary		Set allocations for a month
 //	@Description	Sets allocations for a month for all envelopes that do not have an allocation yet. **Use POST /month endpoint with month and budgetId query parameters instead.**
 //	@Tags			Budgets

pkg/controllers/category.go

@@ -68,6 +68,8 @@ func (co Controller) RegisterCategoryRoutes(r *gin.RouterGroup) {
 	}
 }
 
+// OptionsCategoryList returns the allowed HTTP methods
+//
 //	@Summary		Allowed HTTP verbs
 //	@Description	Returns an empty response with the HTTP Header "allow" set to the allowed HTTP verbs
 //	@Tags			Categories
@@ -79,6 +81,8 @@ func (co Controller) OptionsCategoryList(c *gin.Context) {
 	httputil.OptionsGetPost(c)
 }
 
+// OptionsCategoryDetail returns the allowed HTTP methods
+//
 //	@Summary		Allowed HTTP verbs
 //	@Description	Returns an empty response with the HTTP Header "allow" set to the allowed HTTP verbs
 //	@Tags			Categories
@@ -101,6 +105,8 @@ func (co Controller) OptionsCategoryDetail(c *gin.Context) {
 	httputil.OptionsGetPatchDelete(c)
 }
 
+// CreateCategory creates a new category
+//
 //	@Summary		Create category
 //	@Description	Creates a new category
 //	@Tags			Categories
@@ -132,6 +138,8 @@ func (co Controller) CreateCategory(c *gin.Context) {
 	c.JSON(http.StatusCreated, CategoryResponse{Data: categoryObject})
 }
 
+// GetCategories returns a list of categories filtered by the query parameters
+//
 //	@Summary		Get categories
 //	@Description	Returns a list of categories
 //	@Tags			Categories
@@ -179,6 +187,8 @@ func (co Controller) GetCategories(c *gin.Context) {
 	c.JSON(http.StatusOK, CategoryListResponse{Data: categoryObjects})
 }
 
+// GetCategory returns data for a specific category
+//
 //	@Summary		Get category
 //	@Description	Returns a specific category
 //	@Tags			Categories
@@ -204,6 +214,8 @@ func (co Controller) GetCategory(c *gin.Context) {
 	c.JSON(http.StatusOK, CategoryResponse{Data: categoryObject})
 }
 
+// UpdateCategory updates data for a specific category
+//
 //	@Summary		Update category
 //	@Description	Update an existing category. Only values to be updated need to be specified.
 //	@Tags			Categories
@@ -246,6 +258,8 @@ func (co Controller) UpdateCategory(c *gin.Context) {
 	c.JSON(http.StatusOK, CategoryResponse{Data: categoryObject})
 }
 
+// DeleteCategory deletes a specific category
+//
 //	@Summary		Delete category
 //	@Description	Deletes a category
 //	@Tags			Categories

pkg/controllers/cleanup.go

@@ -8,6 +8,8 @@ import (
 	"github.com/gin-gonic/gin"
 )
 
+// DeleteAll permanently deletes all resources in the database
+//
 //	@Summary		Delete everything
 //	@Description	Permanently deletes all resources
 //	@Tags			v1

pkg/controllers/envelope.go

@@ -74,6 +74,8 @@ func (co Controller) RegisterEnvelopeRoutes(r *gin.RouterGroup) {
 	}
 }
 
+// OptionsEnvelopeList returns the allowed HTTP methods
+//
 //	@Summary		Allowed HTTP verbs
 //	@Description	Returns an empty response with the HTTP Header "allow" set to the allowed HTTP verbs
 //	@Tags			Envelopes
@@ -83,6 +85,8 @@ func (co Controller) OptionsEnvelopeList(c *gin.Context) {
 	httputil.OptionsGetPost(c)
 }
 
+// OptionsEnvelopeDetail returns the allowed HTTP methods
+//
 //	@Summary		Allowed HTTP verbs
 //	@Description	Returns an empty response with the HTTP Header "allow" set to the allowed HTTP verbs
 //	@Tags			Envelopes
@@ -104,6 +108,8 @@ func (co Controller) OptionsEnvelopeDetail(c *gin.Context) {
 	httputil.OptionsGetPatchDelete(c)
 }
 
+// CreateEnvelope creates a new envelope
+//
 //	@Summary		Create envelope
 //	@Description	Creates a new envelope
 //	@Tags			Envelopes
@@ -135,6 +141,8 @@ func (co Controller) CreateEnvelope(c *gin.Context) {
 	c.JSON(http.StatusCreated, EnvelopeResponse{Data: envelopeObject})
 }
 
+// GetEnvelopes returns a list of envelopes filtered by the query parameters
+//
 //	@Summary		Get envelopes
 //	@Description	Returns a list of envelopes
 //	@Tags			Envelopes
@@ -181,6 +189,8 @@ func (co Controller) GetEnvelopes(c *gin.Context) {
 	c.JSON(http.StatusOK, EnvelopeListResponse{Data: envelopeObjects})
 }
 
+// GetEnvelope returns data about a specific envelope
+//
 //	@Summary		Get envelope
 //	@Description	Returns a specific envelope
 //	@Tags			Envelopes
@@ -206,6 +216,8 @@ func (co Controller) GetEnvelope(c *gin.Context) {
 	c.JSON(http.StatusOK, EnvelopeResponse{Data: envelopeObject})
 }
 
+// GetEnvelopeMonth returns month data for a specific envelope
+//
 //	@Summary		Get Envelope month data
 //	@Description	Returns data about an envelope for a for a specific month. **Use GET /month endpoint with month and budgetId query parameters instead.**
 //	@Tags			Envelopes
@@ -251,6 +263,8 @@ func (co Controller) GetEnvelopeMonth(c *gin.Context) {
 	c.JSON(http.StatusOK, EnvelopeMonthResponse{Data: envelopeMonth})
 }
 
+// UpdateEnvelope updates data for an envelope
+//
 //	@Summary		Update envelope
 //	@Description	Updates an existing envelope. Only values to be updated need to be specified.
 //	@Tags			Envelopes
@@ -293,6 +307,8 @@ func (co Controller) UpdateEnvelope(c *gin.Context) {
 	c.JSON(http.StatusOK, EnvelopeResponse{Data: envelopeObject})
 }
 
+// DeleteEnvelope deletes an envelope
+//
 //	@Summary		Delete envelope
 //	@Description	Deletes an envelope
 //	@Tags			Envelopes