Undocumented panic behavior in Handle, StaticFS, and Bind

[quocvibui]

Summary

Three exported public API functions contain panic() calls on invalid input, but none of the doc comments mention the panic conditions. Callers cannot discover the crash risk without reading the source. This is a documentation gap — the panics themselves are reasonable startup-time guards, but they should be documented.

Affected Functions

1. RouterGroup.Handle — panics on invalid HTTP method

File: routergroup.go (around line 105)

router := gin.New()
router.Handle("INVALID-METHOD!", "/test", func(c *gin.Context) {})
// panic: http method INVALID-METHOD! is not valid

Doc says "Handle registers a new request handle and middleware..." — no mention of panic.

2. RouterGroup.StaticFS — panics when path contains URL parameters

File: routergroup.go (around line 205)

router := gin.New()
router.StaticFS("/static/:file", http.Dir("/tmp"))
// panic: URL parameters can not be used when serving a static folder

Doc says "StaticFS works just like Static()..." — no mention of panic.

3. Bind — panics when given a pointer

File: utils.go (around line 25)

type MyStruct struct{ Name string }
gin.Bind(&MyStruct{})
// panic: Bind struct can not be a pointer. Example:
//   Use: gin.Bind(Struct{}) instead of gin.Bind(&Struct{})

Doc says "Bind is a helper function..." — no mention of panic.

Suggested Fix

Add panic documentation to each function's doc comment. For example:

// Handle registers a new request handle and middleware with the given path and method.
// It panics if httpMethod is not a valid HTTP method (uppercase ASCII letters only).
func (group *RouterGroup) Handle(httpMethod, relativePath string, handlers ...HandlerFunc) IRoutes {

// StaticFS works just like Static() but a custom http.FileSystem can be used instead.
// It panics if relativePath contains URL parameters (: or *).
func (group *RouterGroup) StaticFS(relativePath string, fs http.FileSystem) IRoutes {

// Bind is a helper function for given interface object and returns a Gin middleware.
// It panics if val is a pointer; pass the struct value directly (e.g., Bind(Struct{}) not Bind(&Struct{})).
func Bind(val any) HandlerFunc {

Reproduction

All panics confirmed on gin v1.12.0, Go 1.25.1, darwin/arm64.

Environment

• gin version: v1.12.0 (latest)
• Go version: go1.25.1 darwin/arm64

[Folium1]

Hey! I've opened a PR to address this: #4595