ssh/sftp: update comments to use references [...]

3 files changed, 19 insertions, 16 deletions

diff --git a/lib/ssh/sftp/client.go b/lib/ssh/sftp/client.go
index d8a66193..215bf406 100644
--- a/lib/ssh/sftp/client.go
+++ b/lib/ssh/sftp/client.go
@@ -36,7 +36,7 @@ type Client struct {
 
 // NewClient create and initialize new client for SSH file transfer protocol.
 //
-// On failure, it will return ErrSubsystem if the server does not support
+// On failure, it will return [ErrSubsystem] if the server does not support
 // "sftp" subsystem, ErrVersion if the client does not support the
 // server version, and other errors.
 func NewClient(sshc *ssh.Client) (cl *Client, err error) {
@@ -122,7 +122,7 @@ func (cl *Client) CloseFile(fh *FileHandle) (err error) {
 // Create creates or truncates the named file.
 // If the remote file does not exist, it will be created.
 // If the remote file already exists, it will be truncated.
-// On success, it will return the remote FileHandle ready for write only.
+// On success, it will return the remote [FileHandle] ready for write only.
 func (cl *Client) Create(remoteFile string, fa *FileAttrs) (*FileHandle, error) {
 	pflags := OpenFlagWrite | OpenFlagCreate | OpenFlagTruncate
 	return cl.OpenFile(remoteFile, pflags, fa)
@@ -227,7 +227,7 @@ func (cl *Client) Get(remoteFile, localFile string) (err error) {
 }
 
 // Lstat get the file attributes based on the remote file path.
-// Unlike Stat(), the Lstat method does not follow symbolic links.
+// Unlike [Client.Stat], the Lstat method does not follow symbolic links.
 func (cl *Client) Lstat(remoteFile string) (fa *FileAttrs, err error) {
 	var (
 		logp    = "Lstat"
@@ -278,8 +278,8 @@ func (cl *Client) Open(remoteFile string) (fh *FileHandle, err error) {
 	return cl.OpenFile(remoteFile, OpenFlagRead, nil)
 }
 
-// OpenFile open remote file with custom open flag (OpenFlagRead,
-// OpenFlagWrite, and so on) and with specific file attributes.
+// OpenFile open remote file with custom open flag ([OpenFlagRead],
+// [OpenFlagWrite], and so on) and with specific file attributes.
 func (cl *Client) OpenFile(remoteFile string, flags uint32, fa *FileAttrs) (fh *FileHandle, err error) {
 	var (
 		logp = "open"
@@ -386,7 +386,7 @@ func (cl *Client) Put(localFile, remoteFile string) (err error) {
 }
 
 // Read the remote file using handle on specific offset.
-// On end-of-file it will return empty data with io.EOF.
+// On end-of-file it will return empty data with [io.EOF].
 func (cl *Client) Read(fh *FileHandle, offset uint64) (data []byte, err error) {
 	var (
 		logp    = "Read"
diff --git a/lib/ssh/sftp/file_attrs.go b/lib/ssh/sftp/file_attrs.go
index 12b69590..8dc5c343 100644
--- a/lib/ssh/sftp/file_attrs.go
+++ b/lib/ssh/sftp/file_attrs.go
@@ -52,7 +52,7 @@ type FileAttrs struct {
 	mtime       uint32 // attrAcModtime
 }
 
-// NewFileAttrs create and initialize FileAttrs from FileInfo.
+// NewFileAttrs create and initialize [FileAttrs] from [fs.FileInfo].
 func NewFileAttrs(fi fs.FileInfo) (fa *FileAttrs) {
 	fa = &FileAttrs{
 		name: fi.Name(),
@@ -190,7 +190,7 @@ func (fa *FileAttrs) ModTime() time.Time {
 	return time.Unix(int64(fa.mtime), 0)
 }
 
-// Mode return the file mode bits as standard fs.FileMode type.
+// Mode return the file mode bits as standard [fs.FileMode] type.
 func (fa *FileAttrs) Mode() fs.FileMode {
 	return fa.fsMode
 }
@@ -256,7 +256,8 @@ func (fa *FileAttrs) Size() int64 {
 	return int64(fa.size)
 }
 
-// Sys return the pointer to FileAttrs itself.
+// Sys return the pointer to [FileAttrs] itself.
+// This method is added to comply with [fs.FileInfo] interface.
 func (fa *FileAttrs) Sys() interface{} {
 	return fa
 }
diff --git a/lib/ssh/sftp/sftp.go b/lib/ssh/sftp/sftp.go
index e5312431..5ae85160 100644
--- a/lib/ssh/sftp/sftp.go
+++ b/lib/ssh/sftp/sftp.go
@@ -3,19 +3,21 @@
 // license that can be found in the LICENSE file.
 
 // Package sftp implement SSH File Transfer Protocol v3 as defined in
-// draft-ietf-secsh-filexfer-02.txt.
+// [draft-ietf-secsh-filexfer-02.txt].
 //
 // The sftp package extend the golang.org/x/crypto/ssh package by
-// implementing "sftp" subsystem using the ssh.Client connection.
+// implementing "sftp" subsystem using the [ssh.Client] connection.
 //
 // For information, even if scp working normally on server, this package
-// functionalities will not working if the server disable or does not support
-// the "sftp" subsystem.
+// functionalities will not working if the server disable or does not
+// support the "sftp" subsystem.
 // For reference, on openssh, the following configuration
 //
 //	Subsystem sftp /usr/lib/sftp-server
 //
 // should be un-commented on /etc/ssh/sshd_config if its exist.
+//
+// [draft-ietf-secsh-filexfer-02.txt]: https://datatracker.ietf.org/doc/html/draft-ietf-secsh-filexfer-02#page-15
 package sftp
 
 import (
@@ -72,9 +74,9 @@ const (
 // Some response status code from server is mapped to existing errors on
 // standard packages,
 //
-//	SSH_FX_EOF               (1) = io.EOF
-//	SSH_FX_NO_SUCH_FILE      (2) = fs.ErrNotExist
-//	SSH_FX_PERMISSION_DENIED (3) = fs.ErrPermission
+//   - SSH_FX_EOF               (1) = [io.EOF]
+//   - SSH_FX_NO_SUCH_FILE      (2) = [fs.ErrNotExist]
+//   - SSH_FX_PERMISSION_DENIED (3) = [fs.ErrPermission]
 //
 // Other errors is defined below,
 var (