More standard deprecation comment for cap.Compare and cap.IABInit

Based on what I see on go.dev, there seems to be some preferred
comment style for deprecating a function. Use it to help spread
the word.

Signed-off-by: Andrew G. Morgan <morgan@kernel.org>

2 files changed, 39 insertions, 6 deletions

diff --git a/cap/flags.go b/cap/flags.go
index 310ac5d..88ad355 100644
--- a/cap/flags.go
+++ b/cap/flags.go
@@ -148,12 +148,35 @@ func (c *Set) ClearFlag(vec Flag) error {
 	return c.forceFlag(vec, false)
 }
 
-// Compare returns 0 if c and d are identical in content. Otherwise,
-// this function returns a non-zero value of 3 independent bits:
-// (differE ? 1:0) | (differP ? 2:0) | (differI ? 4:0). The Differs()
-// function can be used to test for a difference in a specific Flag.
+// Compare returns 0 if c and d are identical in content.
 //
-// This function is deprecated in favor of (*Set).Cf().
+// Deprecated: Replace with (*Set).Cf().
+//
+// Example, replace this:
+//
+//    diff, err := a.Compare(b)
+//    if err != nil {
+//      return err
+//    }
+//    if diff == 0 {
+//      return nil
+//    }
+//    if diff & (1 << Effective) {
+//      log.Print("a and b difference includes Effective values")
+//    }
+//
+// with this:
+//
+//    diff, err := a.Cf(b)
+//    if err != nil {
+//      return err
+//    }
+//    if diff == 0 {
+//      return nil
+//    }
+//    if diff.Has(Effective) {
+//      log.Print("a and b difference includes Effective values")
+//    }
 func (c *Set) Compare(d *Set) (uint, error) {
 	u, err := c.Cf(d)
 	return uint(u), err
diff --git a/cap/iab.go b/cap/iab.go
index 1be921c..90fc436 100644
--- a/cap/iab.go
+++ b/cap/iab.go
@@ -79,7 +79,17 @@ func NewIAB() *IAB {
 	}
 }
 
-// IABInit is a deprecated alias for the NewIAB function.
+// IABInit allocates a new IAB tuple.
+//
+// Deprecated: Replace with NewIAB.
+//
+// Example, replace this:
+//
+//    iab := IABInit()
+//
+// with this:
+//
+//    iab := NewIAB()
 func IABInit() *IAB {
 	return NewIAB()
 }