doc: minor godoc improvements

Signed-off-by: Aleksa Sarai <[email protected]>

Author: cyphar

doc.go

@@ -16,13 +16,13 @@
 // **not** safe against race conditions where an attacker changes the
 // filesystem after (or during) the [SecureJoin] operation.
 //
-// The new API is made up of [OpenInRoot] and [MkdirAll] (and derived
-// functions). These are safe against racing attackers and have several other
-// protections that are not provided by the legacy API. There are many more
-// operations that most programs expect to be able to do safely, but we do not
-// provide explicit support for them because we want to encourage users to
-// switch to [libpathrs] which is a cross-language next-generation library that
-// is entirely designed around operating on paths safely.
+// The new API is available in the [pathrs-lite] subpackage, and provide
+// protections against racing attackers as well as several other key
+// protections against attacks often seen by container runtimes. As the name
+// suggests, [pathrs-lite] is a stripped down (pure Go) reimplementation of
+// [libpathrs]. The main APIs provided are [OpenInRoot], [MkdirAll], and
+// [procfs.Handle] -- other APIs are not planned to be ported. The long-term
+// goal is for users to migrate to [libpathrs] which is more fully-featured.
 //
 // securejoin has been used by several container runtimes (Docker, runc,
 // Kubernetes, etc) for quite a few years as a de-facto standard for operating
@@ -38,8 +38,10 @@
 // openat2(RESOLVE_BENEATH) which does not fit the usecase of container
 // runtimes and most system tools.
 //
+// [pathrs-lite]: https://pkg.go.dev/github.com/cyphar/filepath-securejoin/pathrs-lite
 // [libpathrs]: https://github.com/openSUSE/libpathrs
 // [OpenInRoot]: https://pkg.go.dev/github.com/cyphar/filepath-securejoin/pathrs-lite#OpenInRoot
 // [MkdirAll]: https://pkg.go.dev/github.com/cyphar/filepath-securejoin/pathrs-lite#MkdirAll
-// [os.Root]; https:///pkg.go.dev/os#Root
+// [procfs.Handle]: https://pkg.go.dev/github.com/cyphar/filepath-securejoin/pathrs-lite/procfs#Handle
+// [os.Root]: https:///pkg.go.dev/os#Root
 package securejoin

pathrs-lite/procfs/procfs_linux.go

@@ -35,10 +35,10 @@ type Handle struct {
 	inner *procfs.Handle
 }
 
-// Close close the resources associated with this Handle. Note that if this
-// Handle was created with [OpenProcRoot], on some kernels the underlying
+// Close close the resources associated with this [Handle]. Note that if this
+// [Handle] was created with [OpenProcRoot], on some kernels the underlying
 // procfs handle is cached and so this Close operation may be a no-op. However,
-// you should always call Close on Handles once you are done with them.
+// you should always call Close on [Handle]s once you are done with them.
 func (proc *Handle) Close() error { return proc.inner.Close() }
 
 // OpenProcRoot tries to open a "safer" handle to "/proc" (i.e., one with the