Fix: Ensure deprecations are parsed correctly

jamietanna · jamietanna · commit eb5e119dac97 · 2023-10-23T17:29:39.000+01:00
It appears that GoDoc does not parse these deprecation warnings as a
deprecation unless there is an explicit blank comment between lines, or
it is the start of a doc comment.
diff --git a/pkg/chi-middleware/oapi_validate.go b/pkg/chi-middleware/oapi_validate.go
@@ -17,14 +17,17 @@ import (
 )
 
 // ErrorHandler is called when there is an error in validation
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/nethttp-middleware#ErrorHandler
 type ErrorHandler func(w http.ResponseWriter, message string, statusCode int)
 
 // MultiErrorHandler is called when oapi returns a MultiError type
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/nethttp-middleware#
 type MultiErrorHandler func(openapi3.MultiError) (int, error)
 
 // Options to customize request validation, openapi3filter specified options will be passed through.
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/nethttp-middleware#Options
 type Options struct {
 	Options           openapi3filter.Options
@@ -36,13 +39,15 @@ type Options struct {
 
 // OapiRequestValidator Creates middleware to validate request by swagger spec.
 // This middleware is good for net/http either since go-chi is 100% compatible with net/http.
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/nethttp-middleware#OapiRequestValidator
 func OapiRequestValidator(swagger *openapi3.T) func(next http.Handler) http.Handler {
 	return OapiRequestValidatorWithOptions(swagger, nil)
 }
 
 // OapiRequestValidatorWithOptions Creates middleware to validate request by swagger spec.
 // This middleware is good for net/http either since go-chi is 100% compatible with net/http.
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/nethttp-middleware#OapiRequestValidatorWithOptions
 func OapiRequestValidatorWithOptions(swagger *openapi3.T, options *Options) func(next http.Handler) http.Handler {
 	if swagger.Servers != nil && (options == nil || !options.SilenceServersWarning) {
@@ -76,6 +81,7 @@ func OapiRequestValidatorWithOptions(swagger *openapi3.T, options *Options) func
 
 // validateRequest is called from the middleware above and actually does the work
 // of validating a request.
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/nethttp-middleware#validateRequest
 func validateRequest(r *http.Request, router routers.Router, options *Options) (int, error) {
 
@@ -124,6 +130,7 @@ func validateRequest(r *http.Request, router routers.Router, options *Options) (
 
 // attempt to get the MultiErrorHandler from the options. If it is not set,
 // return a default handler
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/nethttp-middleware#getMultiErrorHandlerFromOptions
 func getMultiErrorHandlerFromOptions(options *Options) MultiErrorHandler {
 	if options == nil {
@@ -140,6 +147,7 @@ func getMultiErrorHandlerFromOptions(options *Options) MultiErrorHandler {
 // defaultMultiErrorHandler returns a StatusBadRequest (400) and a list
 // of all the errors. This method is called if there are no other
 // methods defined on the options.
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/nethttp-middleware#defaultMultiErrorHandler
 func defaultMultiErrorHandler(me openapi3.MultiError) (int, error) {
 	return http.StatusBadRequest, me
diff --git a/pkg/fiber-middleware/oapi_validate.go b/pkg/fiber-middleware/oapi_validate.go
@@ -23,6 +23,7 @@ type ctxKeyFiberContext struct{}
 type ctxKeyUserData struct{}
 
 // OapiValidatorFromYamlFile creates a validator middleware from a YAML file path
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/fiber-middleware#OapiValidatorFromYamlFile
 func OapiValidatorFromYamlFile(path string) (fiber.Handler, error) {
 
@@ -43,21 +44,25 @@ func OapiValidatorFromYamlFile(path string) (fiber.Handler, error) {
 // OapiRequestValidator is a fiber middleware function which validates incoming HTTP requests
 // to make sure that they conform to the given OAPI 3.0 specification. When
 // OAPI validation fails on the request, we return an HTTP/400 with error message
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/fiber-middleware#OapiRequestValidator
 func OapiRequestValidator(swagger *openapi3.T) fiber.Handler {
 	return OapiRequestValidatorWithOptions(swagger, nil)
 }
 
 // ErrorHandler is called when there is an error in validation
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/fiber-middleware#ErrorHandler
 type ErrorHandler func(c *fiber.Ctx, message string, statusCode int)
 
 // MultiErrorHandler is called when oapi returns a MultiError type
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/fiber-middleware#MultiErrorHandler
 type MultiErrorHandler func(openapi3.MultiError) error
 
 // Options to customize request validation. These are passed through to
 // openapi3filter.
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/fiber-middleware#Options
 type Options struct {
 	Options           openapi3filter.Options
@@ -68,6 +73,7 @@ type Options struct {
 }
 
 // OapiRequestValidatorWithOptions creates a validator from a swagger object, with validation options
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/fiber-middleware#OapiRequestValidatorWithOptions
 func OapiRequestValidatorWithOptions(swagger *openapi3.T, options *Options) fiber.Handler {
 
@@ -95,6 +101,7 @@ func OapiRequestValidatorWithOptions(swagger *openapi3.T, options *Options) fibe
 
 // ValidateRequestFromContext is called from the middleware above and actually does the work
 // of validating a request.
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/fiber-middleware#
 func ValidateRequestFromContext(c *fiber.Ctx, router routers.Router, options *Options) error {
 
@@ -164,6 +171,7 @@ func ValidateRequestFromContext(c *fiber.Ctx, router routers.Router, options *Op
 
 // GetFiberContext gets the fiber context from within requests. It returns
 // nil if not found or wrong type.
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/fiber-middleware#GetFiberContext
 func GetFiberContext(c context.Context) *fiber.Ctx {
 	iface := c.Value(ctxKeyFiberContext{})
@@ -185,6 +193,7 @@ func GetUserData(c context.Context) interface{} {
 
 // getMultiErrorHandlerFromOptions attempts to get the MultiErrorHandler from the options. If it is not set,
 // return a default handler
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/fiber-middleware#getMultiErrorHandlerFromOptions
 func getMultiErrorHandlerFromOptions(options *Options) MultiErrorHandler {
 	if options == nil {
diff --git a/pkg/gin-middleware/oapi_validate.go b/pkg/gin-middleware/oapi_validate.go
@@ -36,6 +36,7 @@ const (
 )
 
 // OapiValidatorFromYamlFile creates a validator middleware from a YAML file path
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/gin-middleware#OapiValidatorFromYamlFile
 func OapiValidatorFromYamlFile(path string) (gin.HandlerFunc, error) {
 	data, err := os.ReadFile(path)
@@ -54,21 +55,25 @@ func OapiValidatorFromYamlFile(path string) (gin.HandlerFunc, error) {
 // OapiRequestValidator is an gin middleware function which validates incoming HTTP requests
 // to make sure that they conform to the given OAPI 3.0 specification. When
 // OAPI validation fails on the request, we return an HTTP/400 with error message
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/gin-middleware#OapiRequestValidator
 func OapiRequestValidator(swagger *openapi3.T) gin.HandlerFunc {
 	return OapiRequestValidatorWithOptions(swagger, nil)
 }
 
 // ErrorHandler is called when there is an error in validation
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/gin-middleware#ErrorHandler
 type ErrorHandler func(c *gin.Context, message string, statusCode int)
 
 // MultiErrorHandler is called when oapi returns a MultiError type
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/gin-middleware#MultiErrorHandler
 type MultiErrorHandler func(openapi3.MultiError) error
 
 // Options to customize request validation. These are passed through to
 // openapi3filter.
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/gin-middleware#Options
 type Options struct {
 	ErrorHandler      ErrorHandler
@@ -81,6 +86,7 @@ type Options struct {
 }
 
 // OapiRequestValidatorWithOptions creates a validator from a swagger object, with validation options
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/gin-middleware#OapiRequestValidatorWithOptions
 func OapiRequestValidatorWithOptions(swagger *openapi3.T, options *Options) gin.HandlerFunc {
 	if swagger.Servers != nil && (options == nil || !options.SilenceServersWarning) {
@@ -117,6 +123,7 @@ func OapiRequestValidatorWithOptions(swagger *openapi3.T, options *Options) gin.
 
 // ValidateRequestFromContext is called from the middleware above and actually does the work
 // of validating a request.
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/gin-middleware#ValidateRequestFromContext
 func ValidateRequestFromContext(c *gin.Context, router routers.Router, options *Options) error {
 	req := c.Request
@@ -180,6 +187,7 @@ func ValidateRequestFromContext(c *gin.Context, router routers.Router, options *
 
 // GetGinContext gets the echo context from within requests. It returns
 // nil if not found or wrong type.
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/gin-middleware#GetGinContext
 func GetGinContext(c context.Context) *gin.Context {
 	iface := c.Value(GinContextKey)
@@ -199,6 +207,7 @@ func GetUserData(c context.Context) interface{} {
 
 // attempt to get the MultiErrorHandler from the options. If it is not set,
 // return a default handler
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/gin-middleware#getMultiErrorHandlerFromOptions
 func getMultiErrorHandlerFromOptions(options *Options) MultiErrorHandler {
 	if options == nil {
@@ -215,6 +224,7 @@ func getMultiErrorHandlerFromOptions(options *Options) MultiErrorHandler {
 // defaultMultiErrorHandler returns a StatusBadRequest (400) and a list
 // of all of the errors. This method is called if there are no other
 // methods defined on the options.
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/gin-middleware#defaultMultiErrorHandler
 func defaultMultiErrorHandler(me openapi3.MultiError) error {
 	return fmt.Errorf("multiple errors encountered: %s", me)
diff --git a/pkg/iris-middleware/oapi_validate.go b/pkg/iris-middleware/oapi_validate.go
@@ -21,6 +21,7 @@ const (
 )
 
 // OapiValidatorFromYamlFile creates a validator middleware from a YAML file path
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/iris-middleware#OapiValidatorFromYamlFile
 func OapiValidatorFromYamlFile(path string) (iris.Handler, error) {
 	data, err := os.ReadFile(path)
@@ -40,21 +41,25 @@ func OapiValidatorFromYamlFile(path string) (iris.Handler, error) {
 // OapiRequestValidator is a iris middleware function which validates incoming HTTP requests
 // to make sure that they conform to the given OAPI 3.0 specification. When
 // OAPI validation fails on the request, we return an HTTP/400 with error message
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/iris-middleware#OapiRequestValidator
 func OapiRequestValidator(swagger *openapi3.T) iris.Handler {
 	return OapiRequestValidatorWithOptions(swagger, nil)
 }
 
 // ErrorHandler is called when there is an error in validation
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/iris-middleware#ErrorHandler
 type ErrorHandler func(ctx iris.Context, message string, statusCode int)
 
 // MultiErrorHandler is called when oapi returns a MultiError type
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/iris-middleware#MultiErrorHandler
 type MultiErrorHandler func(openapi3.MultiError) error
 
 // Options to customize request validation. These are passed through to
 // openapi3filter.
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/iris-middleware#Options
 type Options struct {
 	Options           openapi3filter.Options
@@ -67,6 +72,7 @@ type Options struct {
 }
 
 // OapiRequestValidatorWithOptions creates a validator from a swagger object, with validation options
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/iris-middleware#OapiRequestValidatorWithOptions
 func OapiRequestValidatorWithOptions(swagger *openapi3.T, options *Options) iris.Handler {
 	router, err := gorillamux.NewRouter(swagger)
@@ -89,6 +95,7 @@ func OapiRequestValidatorWithOptions(swagger *openapi3.T, options *Options) iris
 
 // ValidateRequestFromContext is called from the middleware above and actually does the work
 // of validating a request.
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/iris-middleware#ValidateRequestFromContext
 func ValidateRequestFromContext(ctx iris.Context, router routers.Router, options *Options) error {
 	req := ctx.Request()
@@ -152,6 +159,7 @@ func ValidateRequestFromContext(ctx iris.Context, router routers.Router, options
 
 // GetIrisContext gets the iris context from within requests. It returns
 // nil if not found or wrong type.
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/iris-middleware#GetIrisContext
 func GetIrisContext(ctx context.Context) iris.Context {
 	iface := ctx.Value(IrisContextKey)
@@ -173,6 +181,7 @@ func GetUserData(ctx context.Context) interface{} {
 
 // getMultiErrorHandlerFromOptions attempts to get the MultiErrorHandler from the options. If it is not set,
 // return a default handler
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/iris-middleware#getMultiErrorHandlerFromOptions
 func getMultiErrorHandlerFromOptions(options *Options) MultiErrorHandler {
 	if options == nil {
@@ -189,6 +198,7 @@ func getMultiErrorHandlerFromOptions(options *Options) MultiErrorHandler {
 // defaultMultiErrorHandler returns a StatusBadRequest (400) and a list
 // of all the errors. This method is called if there are no other
 // methods defined on the options.
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/iris-middleware#defaultMultiErrorHandler
 func defaultMultiErrorHandler(me openapi3.MultiError) error {
 	return fmt.Errorf("multiple errors encountered: %s", me)
diff --git a/pkg/middleware/oapi_validate.go b/pkg/middleware/oapi_validate.go
@@ -40,6 +40,7 @@ const (
 // to make sure that they conform to the given OAPI 3.0 specification. When
 // OAPI validation fails on the request, we return an HTTP/400.
 // Create validator middleware from a YAML file path
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/echo-middleware#OapiValidatorFromYamlFile
 func OapiValidatorFromYamlFile(path string) (echo.MiddlewareFunc, error) {
 	data, err := os.ReadFile(path)
@@ -55,21 +56,25 @@ func OapiValidatorFromYamlFile(path string) (echo.MiddlewareFunc, error) {
 }
 
 // OapiRequestValidator creates a validator from a swagger object.
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/echo-middleware#OapiRequestValidator
 func OapiRequestValidator(swagger *openapi3.T) echo.MiddlewareFunc {
 	return OapiRequestValidatorWithOptions(swagger, nil)
 }
 
 // ErrorHandler is called when there is an error in validation
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/echo-middleware#ErrorHandler
 type ErrorHandler func(c echo.Context, err *echo.HTTPError) error
 
 // MultiErrorHandler is called when oapi returns a MultiError type
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/echo-middleware#MultiErrorHandler
 type MultiErrorHandler func(openapi3.MultiError) *echo.HTTPError
 
 // Options to customize request validation. These are passed through to
 // openapi3filter.
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/echo-middleware#Options
 type Options struct {
 	ErrorHandler      ErrorHandler
@@ -83,6 +88,7 @@ type Options struct {
 }
 
 // OapiRequestValidatorWithOptions creates a validator from a swagger object, with validation options
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/echo-middleware#OapiRequestValidatorWithOptions
 func OapiRequestValidatorWithOptions(swagger *openapi3.T, options *Options) echo.MiddlewareFunc {
 	if swagger.Servers != nil && (options == nil || !options.SilenceServersWarning) {
@@ -115,6 +121,7 @@ func OapiRequestValidatorWithOptions(swagger *openapi3.T, options *Options) echo
 
 // ValidateRequestFromContext is called from the middleware above and actually does the work
 // of validating a request.
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/echo-middleware#ValidateRequestFromContext
 func ValidateRequestFromContext(ctx echo.Context, router routers.Router, options *Options) *echo.HTTPError {
 	req := ctx.Request()
@@ -197,6 +204,7 @@ func ValidateRequestFromContext(ctx echo.Context, router routers.Router, options
 
 // GetEchoContext gets the echo context from within requests. It returns
 // nil if not found or wrong type.
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/echo-middleware#GetEchoContext
 func GetEchoContext(c context.Context) echo.Context {
 	iface := c.Value(EchoContextKey)
@@ -216,6 +224,7 @@ func GetUserData(c context.Context) interface{} {
 }
 
 // attempt to get the skipper from the options whether it is set or not
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/echo-middleware#getSkipperFromOptions
 func getSkipperFromOptions(options *Options) echomiddleware.Skipper {
 	if options == nil {
@@ -247,6 +256,7 @@ func getMultiErrorHandlerFromOptions(options *Options) MultiErrorHandler {
 // defaultMultiErrorHandler returns a StatusBadRequest (400) and a list
 // of all of the errors. This method is called if there are no other
 // methods defined on the options.
+//
 // Deprecated: This has been replaced by github.com/oapi-codegen/echo-middleware#defaultMultiErrorHandler
 func defaultMultiErrorHandler(me openapi3.MultiError) *echo.HTTPError {
 	return &echo.HTTPError{
diff --git a/pkg/testutil/request_helpers.go b/pkg/testutil/request_helpers.go
