os: more godoc links

Add missing links to *PathError.

Also a few links to O_ flags and Mode and syscall constants.

Change-Id: Ic6ec5780a44942050a83ed07dbf16d6fa9f83eb9
Reviewed-on: https://go-review.googlesource.com/c/go/+/655375
Reviewed-by: Junyang Shao <shaojunyang@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Ian Lance Taylor <iant@google.com>
Auto-Submit: Ian Lance Taylor <iant@google.com>

src/os/file.go

@@ -216,7 +216,7 @@ var errWriteAtInAppendMode = errors.New("os: invalid use of WriteAt on file open
 // It returns the number of bytes written and an error, if any.
 // WriteAt returns a non-nil error when n != len(b).
 //
-// If file was opened with the O_APPEND flag, WriteAt returns an error.
+// If file was opened with the [O_APPEND] flag, WriteAt returns an error.
 func (f *File) WriteAt(b []byte, off int64) (n int, err error) {
 	if err := f.checkValid("write"); err != nil {
 		return 0, err
@@ -280,7 +280,7 @@ func genericWriteTo(f *File, w io.Writer) (int64, error) {
 // according to whence: 0 means relative to the origin of the file, 1 means
 // relative to the current offset, and 2 means relative to the end.
 // It returns the new offset and an error, if any.
-// The behavior of Seek on a file opened with O_APPEND is not specified.
+// The behavior of Seek on a file opened with [O_APPEND] is not specified.
 func (f *File) Seek(offset int64, whence int) (ret int64, err error) {
 	if err := f.checkValid("seek"); err != nil {
 		return 0, err
@@ -304,7 +304,7 @@ func (f *File) WriteString(s string) (n int, err error) {
 
 // Mkdir creates a new directory with the specified name and permission
 // bits (before umask).
-// If there is an error, it will be of type *PathError.
+// If there is an error, it will be of type [*PathError].
 func Mkdir(name string, perm FileMode) error {
 	longName := fixLongPath(name)
 	e := ignoringEINTR(func() error {
@@ -338,7 +338,7 @@ func setStickyBit(name string) error {
 }
 
 // Chdir changes the current working directory to the named directory.
-// If there is an error, it will be of type *PathError.
+// If there is an error, it will be of type [*PathError].
 func Chdir(dir string) error {
 	if e := syscall.Chdir(dir); e != nil {
 		testlog.Open(dir) // observe likely non-existent directory
@@ -365,8 +365,8 @@ func Chdir(dir string) error {
 
 // Open opens the named file for reading. If successful, methods on
 // the returned file can be used for reading; the associated file
-// descriptor has mode O_RDONLY.
-// If there is an error, it will be of type *PathError.
+// descriptor has mode [O_RDONLY].
+// If there is an error, it will be of type [*PathError].
 func Open(name string) (*File, error) {
 	return OpenFile(name, O_RDONLY, 0)
 }
@@ -374,20 +374,20 @@ func Open(name string) (*File, error) {
 // Create creates or truncates the named file. If the file already exists,
 // it is truncated. If the file does not exist, it is created with mode 0o666
 // (before umask). If successful, methods on the returned File can
-// be used for I/O; the associated file descriptor has mode O_RDWR.
+// be used for I/O; the associated file descriptor has mode [O_RDWR].
 // The directory containing the file must already exist.
-// If there is an error, it will be of type *PathError.
+// If there is an error, it will be of type [*PathError].
 func Create(name string) (*File, error) {
 	return OpenFile(name, O_RDWR|O_CREATE|O_TRUNC, 0666)
 }
 
 // OpenFile is the generalized open call; most users will use Open
 // or Create instead. It opens the named file with specified flag
-// (O_RDONLY etc.). If the file does not exist, and the O_CREATE flag
+// ([O_RDONLY] etc.). If the file does not exist, and the [O_CREATE] flag
 // is passed, it is created with mode perm (before umask);
 // the containing directory must exist. If successful,
 // methods on the returned File can be used for I/O.
-// If there is an error, it will be of type *PathError.
+// If there is an error, it will be of type [*PathError].
 func OpenFile(name string, flag int, perm FileMode) (*File, error) {
 	testlog.Open(name)
 	f, err := openFileNolog(name, flag, perm)
@@ -423,7 +423,7 @@ func Rename(oldpath, newpath string) error {
 }
 
 // Readlink returns the destination of the named symbolic link.
-// If there is an error, it will be of type *PathError.
+// If there is an error, it will be of type [*PathError].
 //
 // If the link destination is relative, Readlink returns the relative path
 // without resolving it to an absolute one.
@@ -609,13 +609,13 @@ func UserHomeDir() (string, error) {
 
 // Chmod changes the mode of the named file to mode.
 // If the file is a symbolic link, it changes the mode of the link's target.
-// If there is an error, it will be of type *PathError.
+// If there is an error, it will be of type [*PathError].
 //
 // A different subset of the mode bits are used, depending on the
 // operating system.
 //
-// On Unix, the mode's permission bits, ModeSetuid, ModeSetgid, and
-// ModeSticky are used.
+// On Unix, the mode's permission bits, [ModeSetuid], [ModeSetgid], and
+// [ModeSticky] are used.
 //
 // On Windows, only the 0o200 bit (owner writable) of mode is used; it
 // controls whether the file's read-only attribute is set or cleared.
@@ -623,12 +623,12 @@ func UserHomeDir() (string, error) {
 // and earlier, use a non-zero mode. Use mode 0o400 for a read-only
 // file and 0o600 for a readable+writable file.
 //
-// On Plan 9, the mode's permission bits, ModeAppend, ModeExclusive,
-// and ModeTemporary are used.
+// On Plan 9, the mode's permission bits, [ModeAppend], [ModeExclusive],
+// and [ModeTemporary] are used.
 func Chmod(name string, mode FileMode) error { return chmod(name, mode) }
 
 // Chmod changes the mode of the file to mode.
-// If there is an error, it will be of type *PathError.
+// If there is an error, it will be of type [*PathError].
 func (f *File) Chmod(mode FileMode) error { return f.chmod(mode) }
 
 // SetDeadline sets the read and write deadlines for a File.

src/os/file_plan9.go

@@ -180,7 +180,7 @@ func (file *file) destroy() error {
 }
 
 // Stat returns the FileInfo structure describing file.
-// If there is an error, it will be of type *PathError.
+// If there is an error, it will be of type [*PathError].
 func (f *File) Stat() (FileInfo, error) {
 	if f == nil {
 		return nil, ErrInvalid
@@ -194,7 +194,7 @@ func (f *File) Stat() (FileInfo, error) {
 
 // Truncate changes the size of the file.
 // It does not change the I/O offset.
-// If there is an error, it will be of type *PathError.
+// If there is an error, it will be of type [*PathError].
 func (f *File) Truncate(size int64) error {
 	if f == nil {
 		return ErrInvalid
@@ -356,7 +356,7 @@ func (f *File) seek(offset int64, whence int) (ret int64, err error) {
 
 // Truncate changes the size of the named file.
 // If the file is a symbolic link, it changes the size of the link's target.
-// If there is an error, it will be of type *PathError.
+// If there is an error, it will be of type [*PathError].
 func Truncate(name string, size int64) error {
 	var d syscall.Dir
 
@@ -375,7 +375,7 @@ func Truncate(name string, size int64) error {
 }
 
 // Remove removes the named file or directory.
-// If there is an error, it will be of type *PathError.
+// If there is an error, it will be of type [*PathError].
 func Remove(name string) error {
 	if e := syscall.Remove(name); e != nil {
 		return &PathError{Op: "remove", Path: name, Err: e}
@@ -448,7 +448,7 @@ func chmod(name string, mode FileMode) error {
 //
 // The underlying filesystem may truncate or round the values to a
 // less precise time unit.
-// If there is an error, it will be of type *PathError.
+// If there is an error, it will be of type [*PathError].
 func Chtimes(name string, atime time.Time, mtime time.Time) error {
 	var d syscall.Dir
 
@@ -508,23 +508,23 @@ func readlink(name string) (string, error) {
 // Chown changes the numeric uid and gid of the named file.
 // If the file is a symbolic link, it changes the uid and gid of the link's target.
 // A uid or gid of -1 means to not change that value.
-// If there is an error, it will be of type *PathError.
+// If there is an error, it will be of type [*PathError].
 //
-// On Windows or Plan 9, Chown always returns the syscall.EWINDOWS or
-// EPLAN9 error, wrapped in *PathError.
+// On Windows or Plan 9, Chown always returns the [syscall.EWINDOWS] or
+// [syscall.EPLAN9] error, wrapped in [*PathError].
 func Chown(name string, uid, gid int) error {
 	return &PathError{Op: "chown", Path: name, Err: syscall.EPLAN9}
 }
 
 // Lchown changes the numeric uid and gid of the named file.
 // If the file is a symbolic link, it changes the uid and gid of the link itself.
-// If there is an error, it will be of type *PathError.
+// If there is an error, it will be of type [*PathError].
 func Lchown(name string, uid, gid int) error {
 	return &PathError{Op: "lchown", Path: name, Err: syscall.EPLAN9}
 }
 
 // Chown changes the numeric uid and gid of the named file.
-// If there is an error, it will be of type *PathError.
+// If there is an error, it will be of type [*PathError].
 func (f *File) Chown(uid, gid int) error {
 	if f == nil {
 		return ErrInvalid
@@ -542,7 +542,7 @@ func tempDir() string {
 
 // Chdir changes the current working directory to the file,
 // which must be a directory.
-// If there is an error, it will be of type *PathError.
+// If there is an error, it will be of type [*PathError].
 func (f *File) Chdir() error {
 	if err := f.incref("chdir"); err != nil {
 		return err

src/os/file_posix.go

@@ -101,7 +101,7 @@ func (f *File) chmod(mode FileMode) error {
 // If there is an error, it will be of type [*PathError].
 //
 // On Windows or Plan 9, Chown always returns the [syscall.EWINDOWS] or
-// EPLAN9 error, wrapped in *PathError.
+// [syscall.EPLAN9] error, wrapped in [*PathError].
 func Chown(name string, uid, gid int) error {
 	e := ignoringEINTR(func() error {
 		return syscall.Chown(name, uid, gid)
@@ -117,7 +117,7 @@ func Chown(name string, uid, gid int) error {
 // If there is an error, it will be of type [*PathError].
 //
 // On Windows, it always returns the [syscall.EWINDOWS] error, wrapped
-// in *PathError.
+// in [*PathError].
 func Lchown(name string, uid, gid int) error {
 	e := ignoringEINTR(func() error {
 		return syscall.Lchown(name, uid, gid)
@@ -132,7 +132,7 @@ func Lchown(name string, uid, gid int) error {
 // If there is an error, it will be of type [*PathError].
 //
 // On Windows, it always returns the [syscall.EWINDOWS] error, wrapped
-// in *PathError.
+// in [*PathError].
 func (f *File) Chown(uid, gid int) error {
 	if err := f.checkValid("chown"); err != nil {
 		return err

src/os/file_unix.go

@@ -351,7 +351,7 @@ func (f *File) seek(offset int64, whence int) (ret int64, err error) {
 
 // Truncate changes the size of the named file.
 // If the file is a symbolic link, it changes the size of the link's target.
-// If there is an error, it will be of type *PathError.
+// If there is an error, it will be of type [*PathError].
 func Truncate(name string, size int64) error {
 	e := ignoringEINTR(func() error {
 		return syscall.Truncate(name, size)
@@ -363,7 +363,7 @@ func Truncate(name string, size int64) error {
 }
 
 // Remove removes the named file or (empty) directory.
-// If there is an error, it will be of type *PathError.
+// If there is an error, it will be of type [*PathError].
 func Remove(name string) error {
 	// System call interface forces us to know
 	// whether name is a file or directory.

src/os/file_windows.go

@@ -164,7 +164,7 @@ func Truncate(name string, size int64) error {
 }
 
 // Remove removes the named file or directory.
-// If there is an error, it will be of type *PathError.
+// If there is an error, it will be of type [*PathError].
 func Remove(name string) error {
 	p, e := syscall.UTF16PtrFromString(fixLongPath(name))
 	if e != nil {

src/os/root.go

@@ -77,7 +77,7 @@ const (
 
 // OpenRoot opens the named directory.
 // It follows symbolic links in the directory name.
-// If there is an error, it will be of type *PathError.
+// If there is an error, it will be of type [*PathError].
 func OpenRoot(name string) (*Root, error) {
 	testlog.Open(name)
 	return openRootNolog(name)
@@ -127,7 +127,7 @@ func (r *Root) OpenFile(name string, flag int, perm FileMode) (*File, error) {
 }
 
 // OpenRoot opens the named directory in the root.
-// If there is an error, it will be of type *PathError.
+// If there is an error, it will be of type [*PathError].
 func (r *Root) OpenRoot(name string) (*Root, error) {
 	r.logOpen(name)
 	return openRootInRoot(r, name)