Go Doc is indenting/grouping functions unexpectedly. What is causing it?

Issue

Go Doc is indenting/making a group without me knowingly telling it to.

Here is a screenshot from my browser showing the problem. The four Parse functions should not be indented:

Screenshot showing output of Go Doc in browser. Four of the functions are indented.

What is causing this behaviour?

I’ve tried searching for indents/subsections/grouping in Go Docs but I’ve not found anything beside feature requests. I’m sure the answer to my question is in the documentation somewhere but I can’t find it as I don’t have the correct vocabulary.

I’m relatively new to Go and Go Doc, so I’m assuming the answer is something simple which I’ve overlooked.


Here is an extract of my code. Please let me know if I need to share more code.

status.go

package synop

// Status codes returned when parsing Blocks.
type Status int64

const (
    VALID Status = iota
    NO_DATA
    // code omitted
)

// Other functions omitted

cloudwind_block.go

package synop

import (
    "strings"
)

/*
Extract cloud cover from the cloud-wind block, Cxxxx.
Cloud, C, is the first digit of the block. Cloud over is given in [okta]:
*/
func ParseCloud(block string) (okta int, s Status) {
    slice := [2]int{0, 1}
    return parseIfValid(block, slice, str2int)
}

/*
Extract wind direction from from the cloud-wind block, xDDxxx.
Direction, DD, are the second and third digits.
*/
func ParseDir(block string) (dir string, s Status) {
    slice := [2]int{1, 3}
    return parseIfValid(block, slice, getDir)
}

// Other functions omitted

I have another file, blocks.go, which has almost the same structure as status.go and it does not cause this behaviour. I also don’t know if the problem is caused by the preceding type Status or something in the cloudwind_block.go file.

I’m using // for single-line documentation and /* */ for multi line. I’ve tried making this consistent on the off chance and, as expected, it had no effect.

Solution

The reason for the grouping and indentation is that those functions are considered "constructors" of the type under which they are grouped/indented.

https://go.dev/doc/comment#func (if you scroll down a bit, you’ll see this):

This example also shows that top-level functions returning a type T or pointer *T, perhaps with an additional error result, are shown alongside the type T and its methods, under the assumption that they are T’s constructors.

Answered By – mkopriva

Answer Checked By – Jay B. (GoLangFix Admin)

Leave a Reply

Your email address will not be published.