How deprecate functions?
Go official suggest to using Deprecated:
comment in the doc that wants to deprecate functions, struct fields.
Godoc: documenting Go code
It is using in standard libraries. Ref: standard library.
For example, SEEK_SET
const of os/file.go
, using comment as follows.
// Deprecated: Use io.SeekStart, io.SeekCurrent, and io.SeekEnd.
const (
SEEK_SET int = 0 // seek relative to the origin of the file
SEEK_CUR int = 1 // seek relative to the current offset
SEEK_END int = 2 // seek relative to the end
)
So we should follow this rule in our libraries.
But if you follow this rule, deprecated functions show in Go doc now(Related discussion).
Also, golint does not check about deprecated comments(Related discussion).
As such, go official tools does not have particular behavior for deprecated comments.
Using staticcheck
for check
staticcheck in go-tools can check deprecated things.
staticcheck
reports as follows if using deprecated things.
package main
import (
"net/http/httputil"
)
func main() {
httputil.NewClientConn(nil, nil)
}
$ staticcheck main.go
deprecated.go:8:2: httputil.NewClientConn is deprecated: Use the Client or Transport in package net/http instead. (SA1019)
staticcheck
shows comments as it is behinds Deprecated:
. Using this in CI is good.
Conclusion
- Using
Deprecated:
comment for deprecated things. - Check to deprecated things with
staticcheck
.
Top comments (0)