Exclude comment from go doc

[stevijo]

Is your feature request related to a problem? Please describe. In our projects we use both swag and go doc. But they do not work good together, because the comment is crunched inside one Paragraph with go doc. There is a possibility to exclude the comment from go doc, if the line is starting with //line but it then also disappears from the swagger documentation.

https://github.com/golang/tools/blob/56e9b8e653c818f46a96eb4828aba7be54271a69/godoc/parser.go#L20-L27

Our code looks then something like this:

// ExecCommand godoc
//line @Summary Execute a command by given ID
//line @ID unique ID for command
//line @Accept  json
//line @Produce  json
//line @Param id path int true "Command ID"
//line @Success 200 "{id=cId}"
//line @Failure 400 {object} httputil.HTTPError
//line @Failure 404 {object} httputil.HTTPError
//line @Failure 500 {object} httputil.HTTPError
//line @Router /api/commands/execute/{id} [post]
func (c *Controller) ExecuteCommand(ctx *gin.Context) {

Describe the solution you'd like Generate the swag doc even though a comment is marked with line.

Describe alternatives you've considered Maybe add a command line argument for allowing a //line comment.

Additional context Go doc without //line comments:

[pei0804]

I see. Do you have any idea? @stevijo

[sdghchj]

It's strange that 'go doc' still output comments starting with "//line" in my test.

[nxj-hsadhvani]

Was somebody able to fix this?

[akojo]

golang/go#20925 pretty clearly states that godoc will not support hiding lines. That //line hid some comments was probably a bug that's now fixed.

If you want to process same files using both godoc and swag the best you can do is to add empty lines after each annotation to force line breaks so that godoc docs don't look funny. A better option would probably be to stick to one comment processor per file.

[popatam]

I ran into the same situation, fixed it with:

// indexHandler godoc
// @Summary main metrics page
// @Description main metrics page
// @Tags metrics
// @Produce html
// @Success 200 {string} string
// @Router / [get]
//line for correct view in godoc
// indexHandler main metrics page
func (app *App) indexHandler(w http.ResponseWriter, r *http.Request) {