Golang doesn't recommend you do these; Golint prevented you from doing these; but they might actually be good.

Issues I have found are

Godoc

Part of them is also problems with an IDE, VSCode. It doesn't render multi-line Godoc correctly, unlike JSDoc, JavaDoc, or even Python docstrings.

Adapted from Gin Swagger,

// MainRouter main router
// @title Swagger Example API
// @version 1.0
// @description This is a sample server Petstore server.
// @termsOfService http://swagger.io/terms/

// @contact.name API Support
// @contact.url http://www.swagger.io/support
// @contact.email [e-mail]

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @host petstore.swagger.io
// @BasePath /v2
func MainRouter(r *gin.Engine) {
    url := ginSwagger.URL("http://localhost:8080/swagger/doc.json") // The url pointing to API definition
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, url))
}

When hovering in VSCode, only the last two lines of comments shows; also Golint prevents from compiling, due to MainRouter main router not being directly above the last two lines.

Solution? Easy, via the unrecommended comment style "plus" indentation, as VSCode will recognize this as quotes in Markdown.

// MainRouter main router
/*
  @title Swagger Example API
  @version 1.0
  @description This is a sample server Petstore server.
  @termsOfService http://swagger.io/terms/

  @contact.name API Support
  @contact.url http://www.swagger.io/support
  @contact.email [e-mail]

  @license.name Apache 2.0
  @license.url http://www.apache.org/licenses/LICENSE-2.0.html

  @host petstore.swagger.io
  @BasePath /v2
*/
func MainRouter(r *gin.Engine) {
    url := ginSwagger.URL("http://localhost:8080/swagger/doc.json") // The url pointing to API definition
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, url))
}

If I use JavaDoc or JSDoc, or Python (plus an extension), these will be automated, plus better options.

Linter suggests using reserved words for variable names

I cannot use type_ as variable name. Maybe I can use type0 as a smartie; but Golint doesn't yet suggest correctly.

Linter suggests using reserved words for variable names #393

KernelDeimos posted on Apr 12, 2018

One of the parameters for a function I made is called type_, because "type" is a reserved word.

I'm not sure what the convention should be when the name you want to use happens to be a reserved word, but the linter suggests that it should be type, which isn't a valid variable name.

View on GitHub

And you cannot turn Golint off at all.

Disable/Enable specific Rules #263

steelbrain posted on Dec 01, 2016

Hi everyone 👋

golint is great but sometimes you want all the rules except one and it would be wonderful to specify it somewhere. Other modern linters like ESLint support it, would be good to have it supported in golint as well.

View on GitHub

Varidiac function with interface{}... argument, for function "same-name" overloading

I am not saying that this is good, but why stick to "idiomatic Go"? Good reasons?