fix: mark functions as deprecated with doc comment (#491)

Refer to https://go.dev/wiki/Deprecated

The right way to mark a function as deprecated is to use `Deprecated:`
as the beginning of a doc comment paragraph.

This ensures that various tools (such as static checks) pick up the
deprecation information.

conn.go

@@ -143,7 +143,8 @@ func DialWithTLSConfig(tc *tls.Config) DialOpt {
 
 // DialWithTLSDialer is a wrapper for DialWithTLSConfig with the option to
 // specify a net.Dialer to for example define a timeout or a custom resolver.
-// @deprecated Use DialWithDialer and DialWithTLSConfig instead
+//
+// Deprecated:  Use DialWithDialer and DialWithTLSConfig instead
 func DialWithTLSDialer(tlsConfig *tls.Config, dialer *net.Dialer) DialOpt {
 	return func(dc *DialContext) {
 		dc.tlsConfig = tlsConfig
@@ -195,7 +196,8 @@ func (dc *DialContext) dial(u *url.URL) (net.Conn, error) {
 
 // Dial connects to the given address on the given network using net.Dial
 // and then returns a new Conn for the connection.
-// @deprecated Use DialURL instead.
+//
+// Deprecated:  Use DialURL instead.
 func Dial(network, addr string) (*Conn, error) {
 	c, err := net.DialTimeout(network, addr, DefaultTimeout)
 	if err != nil {
@@ -208,7 +210,8 @@ func Dial(network, addr string) (*Conn, error) {
 
 // DialTLS connects to the given address on the given network using tls.Dial
 // and then returns a new Conn for the connection.
-// @deprecated Use DialURL instead.
+//
+// Deprecated:  Use DialURL instead.
 func DialTLS(network, addr string, config *tls.Config) (*Conn, error) {
 	c, err := tls.DialWithDialer(&net.Dialer{Timeout: DefaultTimeout}, network, addr, config)
 	if err != nil {

control.go

@@ -635,7 +635,7 @@ type ControlDirSync struct {
 	Cookie       []byte
 }
 
-// @deprecated Use NewRequestControlDirSync instead
+// Deprecated:  Use NewRequestControlDirSync instead
 func NewControlDirSync(flags int64, maxAttrCount int64, cookie []byte) *ControlDirSync {
 	return NewRequestControlDirSync(flags, maxAttrCount, cookie)
 }

v3/conn.go

@@ -143,7 +143,8 @@ func DialWithTLSConfig(tc *tls.Config) DialOpt {
 
 // DialWithTLSDialer is a wrapper for DialWithTLSConfig with the option to
 // specify a net.Dialer to for example define a timeout or a custom resolver.
-// @deprecated Use DialWithDialer and DialWithTLSConfig instead
+//
+// Deprecated:  Use DialWithDialer and DialWithTLSConfig instead
 func DialWithTLSDialer(tlsConfig *tls.Config, dialer *net.Dialer) DialOpt {
 	return func(dc *DialContext) {
 		dc.tlsConfig = tlsConfig
@@ -195,7 +196,8 @@ func (dc *DialContext) dial(u *url.URL) (net.Conn, error) {
 
 // Dial connects to the given address on the given network using net.Dial
 // and then returns a new Conn for the connection.
-// @deprecated Use DialURL instead.
+//
+// Deprecated:  Use DialURL instead.
 func Dial(network, addr string) (*Conn, error) {
 	c, err := net.DialTimeout(network, addr, DefaultTimeout)
 	if err != nil {
@@ -208,7 +210,8 @@ func Dial(network, addr string) (*Conn, error) {
 
 // DialTLS connects to the given address on the given network using tls.Dial
 // and then returns a new Conn for the connection.
-// @deprecated Use DialURL instead.
+//
+// Deprecated:  Use DialURL instead.
 func DialTLS(network, addr string, config *tls.Config) (*Conn, error) {
 	c, err := tls.DialWithDialer(&net.Dialer{Timeout: DefaultTimeout}, network, addr, config)
 	if err != nil {

v3/control.go

@@ -635,7 +635,7 @@ type ControlDirSync struct {
 	Cookie       []byte
 }
 
-// @deprecated Use NewRequestControlDirSync instead
+// Deprecated:  Use NewRequestControlDirSync instead
 func NewControlDirSync(flags int64, maxAttrCount int64, cookie []byte) *ControlDirSync {
 	return NewRequestControlDirSync(flags, maxAttrCount, cookie)
 }