Merge pull request moby#151 from kolyshkin/cap-docs

capability: doc improvements

capability/CHANGELOG.md

@@ -5,7 +5,7 @@ from https://github.com/syndtr/gocapability/commit/42c35b4376354fd5.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## 0.2.0 - 2024-09-16
+## [0.2.0] - 2024-09-16
 
 This is the first release after the move to a new home in
 github.com/moby/sys/capability.
@@ -55,6 +55,7 @@ This is an initial release since the fork.
 [LastCap]: https://pkg.go.dev/github.com/moby/sys/capability#LastCap
 
 <!-- Minor releases. -->
+[0.2.0]: https://github.com/moby/sys/releases/tag/capability%2Fv0.2.0
 [0.1.1]: https://github.com/kolyshkin/capability/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/kolyshkin/capability/compare/42c35b4376354fd5...v0.1.0
 

capability/README.md

@@ -2,6 +2,8 @@ This is a fork of (apparently no longer maintained)
 https://github.com/syndtr/gocapability package. It provides basic primitives to
 work with [Linux capabilities][capabilities(7)].
 
+For changes, see [CHANGELOG.md](./CHANGELOG.md).
+
 [![Go Reference](https://pkg.go.dev/badge/github.com/moby/sys/capability/capability.svg)](https://pkg.go.dev/github.com/moby/sys/capability)
 
 ## Alternatives

capability/capability.go

@@ -61,25 +61,26 @@ type Capabilities interface {
 	Apply(kind CapType) error
 }
 
-// NewPid initializes a new Capabilities object for given pid when
+// NewPid initializes a new [Capabilities] object for given pid when
 // it is nonzero, or for the current process if pid is 0.
 //
-// Deprecated: Replace with NewPid2.  For example, replace:
+// Deprecated: Replace with [NewPid2] followed by [Capabilities.Load].
+// For example, replace:
 //
 //	c, err := NewPid(0)
 //	if err != nil {
-//	  return err
+//		return err
 //	}
 //
 // with:
 //
 //	c, err := NewPid2(0)
 //	if err != nil {
-//	  return err
+//		return err
 //	}
 //	err = c.Load()
 //	if err != nil {
-//	  return err
+//		return err
 //	}
 func NewPid(pid int) (Capabilities, error) {
 	c, err := newPid(pid)
@@ -90,32 +91,33 @@ func NewPid(pid int) (Capabilities, error) {
 	return c, err
 }
 
-// NewPid2 initializes a new Capabilities object for given pid when
-// it is nonzero, or for the current process if pid is 0.  This
+// NewPid2 initializes a new [Capabilities] object for given pid when
+// it is nonzero, or for the current process if pid is 0. This
 // does not load the process's current capabilities; to do that you
-// must call Load explicitly.
+// must call [Capabilities.Load] explicitly.
 func NewPid2(pid int) (Capabilities, error) {
 	return newPid(pid)
 }
 
 // NewFile initializes a new Capabilities object for given file path.
 //
-// Deprecated: Replace with NewFile2.  For example, replace:
+// Deprecated: Replace with [NewFile2] followed by [Capabilities.Load].
+// For example, replace:
 //
 //	c, err := NewFile(path)
 //	if err != nil {
-//	  return err
+//		return err
 //	}
 //
 // with:
 //
 //	c, err := NewFile2(path)
 //	if err != nil {
-//	  return err
+//		return err
 //	}
 //	err = c.Load()
 //	if err != nil {
-//	  return err
+//		return err
 //	}
 func NewFile(path string) (Capabilities, error) {
 	c, err := newFile(path)
@@ -126,9 +128,9 @@ func NewFile(path string) (Capabilities, error) {
 	return c, err
 }
 
-// NewFile2 creates a new initialized Capabilities object for given
-// file path.  This does not load the process's current capabilities;
-// to do that you must call Load explicitly.
+// NewFile2 creates a new initialized [Capabilities] object for given
+// file path. This does not load the process's current capabilities;
+// to do that you must call [Capabilities.Load] explicitly.
 func NewFile2(path string) (Capabilities, error) {
 	return newFile(path)
 }