encoding/binary: missing documentation for BigEndian and LittleEndian functions

[nilskch]

Go version

go version go1.22.3 darwin/arm64

Output of go env in your module/workspace:

It is not important here and contains information about my employer that I do not want to share.

What did you do?

I wanted to use the functions of the littleEndian and bigEndian types and noticed that gopls does not provide a function documentation. I was unsure about the exact behavior and needed to look up the implementation.

What did you see happen?

gopls just provides the function definition with description (see here).

What did you expect to see?

I wanted to see a documentation of those functions. Would you accept a PR that adds the documentation?

[gabyhelp]

Similar Issues

• cmd/godoc: encoding/binary does not show BigEndian, LittleEndian #2998

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[seankhliao]

Given the function names are quite self-explanatory, what other information would the function docs contain?

[nilskch]

For example, PutUint16([]byte, uint16) accepts byte slices of any length. Where will the 2 bytes be stored? At the beginning or the end of the slice? This behavior is not intuitive to me just from the function definition.

[dr2chase]

I checked that adding the documentation would work (the bug referenced by gabyhelp made me wonder) so I think a pull request would be fine. There may be some back-and-forth on the exact wording in review, but if it tripped you up, it is probably a problem for other people, and is worth fixing.

There's a process, if this is too much, say so (that's also useful feedback) and maybe someone else will write the docs and you can comment on whether that meets your needs.

[rsc]

They have documentation. https://pkg.go.dev/encoding/binary#pkg-variables
It sounds like you are saying gopls does not show the documentation?

[nilskch]

@rsc the variables LittleEndian, BigEndian and NativeEndian have documentation. The interfaces ByteOrder and AppendByteOrder have documentation as well, but the functions of the structs littleEndian and bigEndian that implement those interfaces don't (littleEndian, bigEndian).

When you hover over binary.LittleEndian.PutUint16 gopls only returns the function definition func (littleEndian) PutUint16(b []byte, v uint16) without any further documentation and therefore I needed to lookup the implementation.

[nilskch]

There may be some back-and-forth on the exact wording in review, but if it tripped you up, it is probably a problem for other people, and is worth fixing.

@dr2chase I will look into it this weekend.

[gopherbot]

Change https://go.dev/cl/638936 mentions this issue: encoding/binary: adds documentation for endian methods

[dmitshur]

CC @golang/tools-team for awareness of how gopls comes into play here.

[adonovan]

I think gopls is working as intended. The binary package exposes variables of unexported types, and the methods of those types are undocumented. The solution is to document those methods; https://go.dev/cl/638936 does this.