Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

x/crypto/nacl: function docs should describe return values #71234

Open
shoenseiwaso opened this issue Jan 12, 2025 · 2 comments · May be fixed by golang/crypto#309
Open

x/crypto/nacl: function docs should describe return values #71234

shoenseiwaso opened this issue Jan 12, 2025 · 2 comments · May be fixed by golang/crypto#309
Labels
Documentation Issues describing a change to documentation. NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Milestone
Unreleased

Comments

@shoenseiwaso
Copy link
Contributor

Go version

go version go1.23.0 darwin/arm64

Output of go env in your module/workspace:

GO111MODULE=''
GOARCH='arm64'
GOBIN=''
GOCACHE='/Users/jeff/Library/Caches/go-build'
GOENV='/Users/jeff/Library/Application Support/go/env'
GOEXE=''
GOEXPERIMENT=''
GOFLAGS=''
GOHOSTARCH='arm64'
GOHOSTOS='darwin'
GOINSECURE=''
GOMODCACHE='/Users/jeff/go/pkg/mod'
GOOS='darwin'
GOPATH='/Users/jeff/go'
GOPRIVATE='github.com/curvegrid/*'
GOPROXY='https://proxy.golang.org,direct'
GOROOT='/opt/homebrew/Cellar/go/1.23.0/libexec'
GOSUMDB='sum.golang.org'
GOTMPDIR=''
GOTOOLCHAIN='auto'
GOTOOLDIR='/opt/homebrew/Cellar/go/1.23.0/libexec/pkg/tool/darwin_arm64'
GOVCS=''
GOVERSION='go1.23.0'
GODEBUG=''
GOTELEMETRY='local'
GOTELEMETRYDIR='/Users/jeff/Library/Application Support/go/telemetry'
GCCGO='gccgo'
GOARM64='v8.0'
AR='ar'
CC='cc'
CXX='c++'
CGO_ENABLED='1'
GOMOD='/dev/null'
GOWORK=''
CGO_CFLAGS='-O2 -g'
CGO_CPPFLAGS=''
CGO_CXXFLAGS='-O2 -g'
CGO_FFLAGS='-O2 -g'
CGO_LDFLAGS='-O2 -g'
PKG_CONFIG='pkg-config'
GOGCCFLAGS='-fPIC -arch arm64 -pthread -fno-caret-diagnostics -Qunused-arguments -fmessage-length=0 -ffile-prefix-map=/var/folders/vv/s0_ykdm97l989629xrkbsy6m0000gn/T/go-build2163110709=/tmp/go-build -gno-record-gcc-switches -fno-common'

What did you do?

The inline documentation for the functions in golang.org/x/crypto/nacl do not describe their return values.

What did you see happen?

For example, secretbox.Open() and secretbox.Seal() should describe what their return values are. Contrast this with, for example, the documentation for poly1305, which either describes what the return value is ("Size returns the number of bytes Sum will return.") or makes it implicit through named return values (func (h *MAC) Write(p []byte) (n int, err error)).

What did you expect to see?

See above comment
@shoenseiwaso shoenseiwaso changed the title import/path: issue title x/crypto: issue title Jan 12, 2025
@gopherbot gopherbot added this to the Unreleased milestone Jan 12, 2025
@shoenseiwaso shoenseiwaso changed the title x/crypto: issue title x/crypto: functions in golang.org/x/crypto/nacl should describe their return values Jan 12, 2025
@shoenseiwaso shoenseiwaso linked a pull request Jan 12, 2025 that will close this issue
Open
@gopherbot
Copy link
Contributor

Change https://go.dev/cl/642315 mentions this issue: x/crypto: add return value descriptions to select golang.org/x/crypto/nacl functions

@gabyhelp gabyhelp added the Documentation Issues describing a change to documentation. label Jan 12, 2025
@seankhliao seankhliao changed the title x/crypto: functions in golang.org/x/crypto/nacl should describe their return values x/crypto/nacl: function docs should describe return values Jan 12, 2025
@mknyszek
Copy link
Contributor

CC @golang/security

@mknyszek mknyszek added the NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. label Jan 13, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Documentation Issues describing a change to documentation. NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Projects
None yet
Milestone
Unreleased
4 participants
@mknyszek @shoenseiwaso @gopherbot @gabyhelp