From b3abdd67effad1f7cdf22c862801f23154d5ab2c Mon Sep 17 00:00:00 2001
From: Michal Rostecki <vadorovsky@protonmail.com>
Date: Sun, 24 Nov 2024 15:37:07 +0100
Subject: [PATCH] doc(aya): Improve the description of `take_link` methods

Don't mix the tenses.
---
 aya/src/programs/cgroup_device.rs    | 7 ++++---
 aya/src/programs/cgroup_skb.rs       | 7 ++++---
 aya/src/programs/cgroup_sock.rs      | 7 ++++---
 aya/src/programs/cgroup_sock_addr.rs | 7 ++++---
 aya/src/programs/cgroup_sockopt.rs   | 7 ++++---
 aya/src/programs/cgroup_sysctl.rs    | 7 ++++---
 aya/src/programs/extension.rs        | 7 ++++---
 aya/src/programs/fentry.rs           | 7 ++++---
 aya/src/programs/fexit.rs            | 6 +++---
 aya/src/programs/kprobe.rs           | 7 ++++---
 aya/src/programs/lirc_mode2.rs       | 6 +++---
 aya/src/programs/lsm.rs              | 6 +++---
 aya/src/programs/perf_event.rs       | 7 ++++---
 aya/src/programs/raw_trace_point.rs  | 7 ++++---
 aya/src/programs/sk_lookup.rs        | 7 ++++---
 aya/src/programs/sk_msg.rs           | 7 ++++---
 aya/src/programs/sk_skb.rs           | 6 +++---
 aya/src/programs/sock_ops.rs         | 7 ++++---
 aya/src/programs/socket_filter.rs    | 7 ++++---
 aya/src/programs/tc.rs               | 7 ++++---
 aya/src/programs/tp_btf.rs           | 7 ++++---
 aya/src/programs/trace_point.rs      | 7 ++++---
 aya/src/programs/uprobe.rs           | 7 ++++---
 aya/src/programs/xdp.rs              | 6 +++---
 24 files changed, 91 insertions(+), 72 deletions(-)

diff --git a/aya/src/programs/cgroup_device.rs b/aya/src/programs/cgroup_device.rs
index 87c5d4a2..22975742 100644
--- a/aya/src/programs/cgroup_device.rs
+++ b/aya/src/programs/cgroup_device.rs
@@ -99,10 +99,11 @@ impl CgroupDevice {
         }
     }
 
-    /// Takes ownership of the link referenced by the provided link_id.
+    /// Takes ownership of the link referenced by the provided `link_id`.
     ///
-    /// The link will be detached on `Drop` and the caller is now responsible
-    /// for managing its lifetime.
+    /// The caller takes the responsibility of managing the lifetime of the
+    /// link. When the returned [`CgroupDeviceLink`] is dropped, the link is
+    /// detached.
     pub fn take_link(
         &mut self,
         link_id: CgroupDeviceLinkId,
diff --git a/aya/src/programs/cgroup_skb.rs b/aya/src/programs/cgroup_skb.rs
index 637e897a..7286a36a 100644
--- a/aya/src/programs/cgroup_skb.rs
+++ b/aya/src/programs/cgroup_skb.rs
@@ -125,10 +125,11 @@ impl CgroupSkb {
         }
     }
 
-    /// Takes ownership of the link referenced by the provided link_id.
+    /// Takes ownership of the link referenced by the provided `link_id`.
     ///
-    /// The link will be detached on `Drop` and the caller is now responsible
-    /// for managing its lifetime.
+    /// The caller takes the responsibility of managing the lifetime of the
+    /// link. When the returned [`CgroupSkbLink`] is dropped, the link is
+    /// detached.
     pub fn take_link(&mut self, link_id: CgroupSkbLinkId) -> Result<CgroupSkbLink, ProgramError> {
         self.data.take_link(link_id)
     }
diff --git a/aya/src/programs/cgroup_sock.rs b/aya/src/programs/cgroup_sock.rs
index cc5db22f..55cbf75f 100644
--- a/aya/src/programs/cgroup_sock.rs
+++ b/aya/src/programs/cgroup_sock.rs
@@ -103,10 +103,11 @@ impl CgroupSock {
         }
     }
 
-    /// Takes ownership of the link referenced by the provided link_id.
+    /// Takes ownership of the link referenced by the provided `link_id`.
     ///
-    /// The link will be detached on `Drop` and the caller is now responsible
-    /// for managing its lifetime.
+    /// The caller takes the responsibility of managing the lifetime of the
+    /// link. When the returned [`CgroupSockLink`] is dropped, the link is
+    /// detached.
     pub fn take_link(&mut self, link_id: CgroupSockLinkId) -> Result<CgroupSockLink, ProgramError> {
         self.data.take_link(link_id)
     }
diff --git a/aya/src/programs/cgroup_sock_addr.rs b/aya/src/programs/cgroup_sock_addr.rs
index a31d8cfd..5827fa3e 100644
--- a/aya/src/programs/cgroup_sock_addr.rs
+++ b/aya/src/programs/cgroup_sock_addr.rs
@@ -104,10 +104,11 @@ impl CgroupSockAddr {
         }
     }
 
-    /// Takes ownership of the link referenced by the provided link_id.
+    /// Takes ownership of the link referenced by the provided `link_id`.
     ///
-    /// The link will be detached on `Drop` and the caller is now responsible
-    /// for managing its lifetime.
+    /// The caller takes the responsibility of managing the lifetime of the
+    /// link. When the returned [`CgroupSockAddrLink`] is dropped, the link is
+    /// detached.
     pub fn take_link(
         &mut self,
         link_id: CgroupSockAddrLinkId,
diff --git a/aya/src/programs/cgroup_sockopt.rs b/aya/src/programs/cgroup_sockopt.rs
index ee9d40b2..c0cbe320 100644
--- a/aya/src/programs/cgroup_sockopt.rs
+++ b/aya/src/programs/cgroup_sockopt.rs
@@ -103,10 +103,11 @@ impl CgroupSockopt {
         }
     }
 
-    /// Takes ownership of the link referenced by the provided link_id.
+    /// Takes ownership of the link referenced by the provided `link_id`.
     ///
-    /// The link will be detached on `Drop` and the caller is now responsible
-    /// for managing its lifetime.
+    /// The caller takes the responsibility of managing the lifetime of the
+    /// link. When the returned [`CgroupSockoptLink`] is dropped, the link is
+    /// detached.
     pub fn take_link(
         &mut self,
         link_id: CgroupSockoptLinkId,
diff --git a/aya/src/programs/cgroup_sysctl.rs b/aya/src/programs/cgroup_sysctl.rs
index fd997aa1..edb51367 100644
--- a/aya/src/programs/cgroup_sysctl.rs
+++ b/aya/src/programs/cgroup_sysctl.rs
@@ -98,10 +98,11 @@ impl CgroupSysctl {
         }
     }
 
-    /// Takes ownership of the link referenced by the provided link_id.
+    /// Takes ownership of the link referenced by the provided `link_id`.
     ///
-    /// The link will be detached on `Drop` and the caller is now responsible
-    /// for managing its lifetime.
+    /// The caller takes the responsibility of managing the lifetime of the
+    /// link. When the returned [`CgroupSysctlLink`] is dropped, the link is
+    /// detached.
     pub fn take_link(
         &mut self,
         link_id: CgroupSysctlLinkId,
diff --git a/aya/src/programs/extension.rs b/aya/src/programs/extension.rs
index 68d77f38..f8a15b70 100644
--- a/aya/src/programs/extension.rs
+++ b/aya/src/programs/extension.rs
@@ -160,10 +160,11 @@ impl Extension {
         self.data.links.remove(link_id)
     }
 
-    /// Takes ownership of the link referenced by the provided link_id.
+    /// Takes ownership of the link referenced by the provided `link_id`.
     ///
-    /// The link will be detached on `Drop` and the caller is now responsible
-    /// for managing its lifetime.
+    /// The caller takes the responsibility of managing the lifetime of the
+    /// link. When the returned [`ExtensionLink`] is dropped, the link is
+    /// detached.
     pub fn take_link(&mut self, link_id: ExtensionLinkId) -> Result<ExtensionLink, ProgramError> {
         self.data.take_link(link_id)
     }
diff --git a/aya/src/programs/fentry.rs b/aya/src/programs/fentry.rs
index 0a1d082f..b74bb6e7 100644
--- a/aya/src/programs/fentry.rs
+++ b/aya/src/programs/fentry.rs
@@ -75,10 +75,11 @@ impl FEntry {
         self.data.links.remove(link_id)
     }
 
-    /// Takes ownership of the link referenced by the provided link_id.
+    /// Takes ownership of the link referenced by the provided `link_id`.
     ///
-    /// The link will be detached on `Drop` and the caller is now responsible
-    /// for managing its lifetime.
+    /// The caller takes the responsibility of managing the lifetime of the
+    /// link. When the returned [`FEntryLink`] is dropped, the link is
+    /// detached.
     pub fn take_link(&mut self, link_id: FEntryLinkId) -> Result<FEntryLink, ProgramError> {
         self.data.take_link(link_id)
     }
diff --git a/aya/src/programs/fexit.rs b/aya/src/programs/fexit.rs
index 5efca285..a97123b8 100644
--- a/aya/src/programs/fexit.rs
+++ b/aya/src/programs/fexit.rs
@@ -75,10 +75,10 @@ impl FExit {
         self.data.links.remove(link_id)
     }
 
-    /// Takes ownership of the link referenced by the provided link_id.
+    /// Takes ownership of the link referenced by the provided `link_id`.
     ///
-    /// The link will be detached on `Drop` and the caller is now responsible
-    /// for managing its lifetime.
+    /// The caller takes the responsibility of managing the lifetime of the
+    /// link. When the returned `FExitLink` is dropped, the link is detached.
     pub fn take_link(&mut self, link_id: FExitLinkId) -> Result<FExitLink, ProgramError> {
         self.data.take_link(link_id)
     }
diff --git a/aya/src/programs/kprobe.rs b/aya/src/programs/kprobe.rs
index 81e830e9..28ce4704 100644
--- a/aya/src/programs/kprobe.rs
+++ b/aya/src/programs/kprobe.rs
@@ -88,10 +88,11 @@ impl KProbe {
         self.data.links.remove(link_id)
     }
 
-    /// Takes ownership of the link referenced by the provided link_id.
+    /// Takes ownership of the link referenced by the provided `link_id`.
     ///
-    /// The link will be detached on `Drop` and the caller is now responsible
-    /// for managing its lifetime.
+    /// The caller takes the responsibility of managing the lifetime of the
+    /// link. When the returned [`KProbeLink`] is dropped, the link is
+    /// detached.
     pub fn take_link(&mut self, link_id: KProbeLinkId) -> Result<KProbeLink, ProgramError> {
         self.data.take_link(link_id)
     }
diff --git a/aya/src/programs/lirc_mode2.rs b/aya/src/programs/lirc_mode2.rs
index fecd261d..d63dc8d6 100644
--- a/aya/src/programs/lirc_mode2.rs
+++ b/aya/src/programs/lirc_mode2.rs
@@ -89,10 +89,10 @@ impl LircMode2 {
         self.data.links.remove(link_id)
     }
 
-    /// Takes ownership of the link referenced by the provided link_id.
+    /// Takes ownership of the link referenced by the provided `link_id`.
     ///
-    /// The link will be detached on `Drop` and the caller is now responsible
-    /// for managing its lifetime.
+    /// The caller takes the responsibility of managing the lifetime of the
+    /// link. When the returned [`LircLink`] is dropped, the link is detached.
     pub fn take_link(&mut self, link_id: LircLinkId) -> Result<LircLink, ProgramError> {
         self.data.take_link(link_id)
     }
diff --git a/aya/src/programs/lsm.rs b/aya/src/programs/lsm.rs
index 7c1d9ddf..6dfa6435 100644
--- a/aya/src/programs/lsm.rs
+++ b/aya/src/programs/lsm.rs
@@ -81,10 +81,10 @@ impl Lsm {
         self.data.links.remove(link_id)
     }
 
-    /// Takes ownership of the link referenced by the provided link_id.
+    /// Takes ownership of the link referenced by the provided `link_id`.
     ///
-    /// The link will be detached on `Drop` and the caller is now responsible
-    /// for managing its lifetime.
+    /// The caller takes the responsibility of managing the lifetime of the
+    /// link. When the returned [`LsmLink`] is dropped, the link is detached.
     pub fn take_link(&mut self, link_id: LsmLinkId) -> Result<LsmLink, ProgramError> {
         self.data.take_link(link_id)
     }
diff --git a/aya/src/programs/perf_event.rs b/aya/src/programs/perf_event.rs
index 587d6499..84f40983 100644
--- a/aya/src/programs/perf_event.rs
+++ b/aya/src/programs/perf_event.rs
@@ -191,10 +191,11 @@ impl PerfEvent {
         self.data.links.remove(link_id)
     }
 
-    /// Takes ownership of the link referenced by the provided link_id.
+    /// Takes ownership of the link referenced by the provided `link_id`.
     ///
-    /// The link will be detached on `Drop` and the caller is now responsible
-    /// for managing its lifetime.
+    /// The caller takes the responsibility of managing the lifetime of the
+    /// link. When the returned [`PerfEventLink`] is dropped, the link is
+    /// detached.
     pub fn take_link(&mut self, link_id: PerfEventLinkId) -> Result<PerfEventLink, ProgramError> {
         self.data.take_link(link_id)
     }
diff --git a/aya/src/programs/raw_trace_point.rs b/aya/src/programs/raw_trace_point.rs
index 617ebc81..13c0d17f 100644
--- a/aya/src/programs/raw_trace_point.rs
+++ b/aya/src/programs/raw_trace_point.rs
@@ -60,10 +60,11 @@ impl RawTracePoint {
         self.data.links.remove(link_id)
     }
 
-    /// Takes ownership of the link referenced by the provided link_id.
+    /// Takes ownership of the link referenced by the provided `link_id`.
     ///
-    /// The link will be detached on `Drop` and the caller is now responsible
-    /// for managing its lifetime.
+    /// The caller takes the responsibility of managing the lifetime of the
+    /// link. When the returned [`RawTracePointLink`] is dropped, the link is
+    /// detached.
     pub fn take_link(
         &mut self,
         link_id: RawTracePointLinkId,
diff --git a/aya/src/programs/sk_lookup.rs b/aya/src/programs/sk_lookup.rs
index 065001ce..c9c3fb88 100644
--- a/aya/src/programs/sk_lookup.rs
+++ b/aya/src/programs/sk_lookup.rs
@@ -82,10 +82,11 @@ impl SkLookup {
             .insert(SkLookupLink::new(FdLink::new(link_fd)))
     }
 
-    /// Takes ownership of the link referenced by the provided link_id.
+    /// Takes ownership of the link referenced by the provided `link_id`.
     ///
-    /// The link will be detached on `Drop` and the caller is now responsible
-    /// for managing its lifetime.
+    /// The caller takes the responsibility of managing the lifetime of the
+    /// link. When the returned [`SkLookupLink`] is dropped, the link is
+    /// detached.
     pub fn take_link(&mut self, link_id: SkLookupLinkId) -> Result<SkLookupLink, ProgramError> {
         self.data.take_link(link_id)
     }
diff --git a/aya/src/programs/sk_msg.rs b/aya/src/programs/sk_msg.rs
index 95510cf2..45b333e1 100644
--- a/aya/src/programs/sk_msg.rs
+++ b/aya/src/programs/sk_msg.rs
@@ -97,10 +97,11 @@ impl SkMsg {
         self.data.links.remove(link_id)
     }
 
-    /// Takes ownership of the link referenced by the provided link_id.
+    /// Takes ownership of the link referenced by the provided `link_id`.
     ///
-    /// The link will be detached on `Drop` and the caller is now responsible
-    /// for managing its lifetime.
+    /// The caller takes the responsibility of managing the lifetime of the
+    /// link. When the returned  [`SkMsgLink`] is dropped, the link is
+    /// detached.
     pub fn take_link(&mut self, link_id: SkMsgLinkId) -> Result<SkMsgLink, ProgramError> {
         self.data.take_link(link_id)
     }
diff --git a/aya/src/programs/sk_skb.rs b/aya/src/programs/sk_skb.rs
index eabce593..16a53874 100644
--- a/aya/src/programs/sk_skb.rs
+++ b/aya/src/programs/sk_skb.rs
@@ -103,10 +103,10 @@ impl SkSkb {
         self.data.links.remove(link_id)
     }
 
-    /// Takes ownership of the link referenced by the provided link_id.
+    /// Takes ownership of the link referenced by the provided `link_id`.
     ///
-    /// The link will be detached on `Drop` and the caller is now responsible
-    /// for managing its lifetime.
+    /// The caller takes the responsibility of managing the lifetime of the
+    /// link. When the returned [`SkSkbLink`] is dropped, the link is detached.
     pub fn take_link(&mut self, link_id: SkSkbLinkId) -> Result<SkSkbLink, ProgramError> {
         self.data.take_link(link_id)
     }
diff --git a/aya/src/programs/sock_ops.rs b/aya/src/programs/sock_ops.rs
index 62573215..75c3a97f 100644
--- a/aya/src/programs/sock_ops.rs
+++ b/aya/src/programs/sock_ops.rs
@@ -100,10 +100,11 @@ impl SockOps {
         self.data.links.remove(link_id)
     }
 
-    /// Takes ownership of the link referenced by the provided link_id.
+    /// Takes ownership of the link referenced by the provided `link_id`.
     ///
-    /// The link will be detached on `Drop` and the caller is now responsible
-    /// for managing its lifetime.
+    /// The caller takes the responsibility of managing the lifetime of the
+    /// link. When the returned [`SockOpsLink`] is dropped, the link is
+    /// detached.
     pub fn take_link(&mut self, link_id: SockOpsLinkId) -> Result<SockOpsLink, ProgramError> {
         self.data.take_link(link_id)
     }
diff --git a/aya/src/programs/socket_filter.rs b/aya/src/programs/socket_filter.rs
index 02be9e05..78152bd8 100644
--- a/aya/src/programs/socket_filter.rs
+++ b/aya/src/programs/socket_filter.rs
@@ -105,10 +105,11 @@ impl SocketFilter {
         self.data.links.remove(link_id)
     }
 
-    /// Takes ownership of the link referenced by the provided link_id.
+    /// Takes ownership of the link referenced by the provided `link_id`.
     ///
-    /// The link will be detached on `Drop` and the caller is now responsible
-    /// for managing its lifetime.
+    /// The caller takes the responsibility of managing the lifetime of the
+    /// link. When the returned [`SocketFilterLink`] is dropped, the link is
+    /// detached.
     pub fn take_link(
         &mut self,
         link_id: SocketFilterLinkId,
diff --git a/aya/src/programs/tc.rs b/aya/src/programs/tc.rs
index 9f55fe92..5a2e6c2c 100644
--- a/aya/src/programs/tc.rs
+++ b/aya/src/programs/tc.rs
@@ -322,10 +322,11 @@ impl SchedClassifier {
         self.data.links.remove(link_id)
     }
 
-    /// Takes ownership of the link referenced by the provided link_id.
+    /// Takes ownership of the link referenced by the provided `link_id`.
     ///
-    /// The link will be detached on `Drop` and the caller is now responsible
-    /// for managing its lifetime.
+    /// The caller takes the responsibility of managing the lifetime of the
+    /// link. When the returned [`SchedClassifierLink`] is dropped, the link is
+    /// detached.
     pub fn take_link(
         &mut self,
         link_id: SchedClassifierLinkId,
diff --git a/aya/src/programs/tp_btf.rs b/aya/src/programs/tp_btf.rs
index 8c235d43..549d5ae7 100644
--- a/aya/src/programs/tp_btf.rs
+++ b/aya/src/programs/tp_btf.rs
@@ -79,10 +79,11 @@ impl BtfTracePoint {
         self.data.links.remove(link_id)
     }
 
-    /// Takes ownership of the link referenced by the provided link_id.
+    /// Takes ownership of the link referenced by the provided `link_id`.
     ///
-    /// The link will be detached on `Drop` and the caller is now responsible
-    /// for managing its lifetime.
+    /// The caller takes the responsibility of managing the lifetime of the
+    /// link. When the returned [`BtfTracePointLink`] is dropped, the link is
+    /// detached.
     pub fn take_link(
         &mut self,
         link_id: BtfTracePointLinkId,
diff --git a/aya/src/programs/trace_point.rs b/aya/src/programs/trace_point.rs
index 4ce0be9a..3e3cea96 100644
--- a/aya/src/programs/trace_point.rs
+++ b/aya/src/programs/trace_point.rs
@@ -89,10 +89,11 @@ impl TracePoint {
         self.data.links.remove(link_id)
     }
 
-    /// Takes ownership of the link referenced by the provided link_id.
+    /// Takes ownership of the link referenced by the provided `link_id`.
     ///
-    /// The link will be detached on `Drop` and the caller is now responsible
-    /// for managing its lifetime.
+    /// The caller takes the responsibility of managing the lifetime of the
+    /// link. When the returned [`TracePointLink`] is dropped, the link is
+    /// detached.
     pub fn take_link(&mut self, link_id: TracePointLinkId) -> Result<TracePointLink, ProgramError> {
         self.data.take_link(link_id)
     }
diff --git a/aya/src/programs/uprobe.rs b/aya/src/programs/uprobe.rs
index 737166ba..afd0f625 100644
--- a/aya/src/programs/uprobe.rs
+++ b/aya/src/programs/uprobe.rs
@@ -104,10 +104,11 @@ impl UProbe {
         self.data.links.remove(link_id)
     }
 
-    /// Takes ownership of the link referenced by the provided link_id.
+    /// Takes ownership of the link referenced by the provided `link_id`.
     ///
-    /// The link will be detached on `Drop` and the caller is now responsible
-    /// for managing its lifetime.
+    /// The caller takes the responsibility of managing the lifetime of the
+    /// link. When the returned [`UProbeLink`] is dropped, the link is
+    /// detached.
     pub fn take_link(&mut self, link_id: UProbeLinkId) -> Result<UProbeLink, ProgramError> {
         self.data.take_link(link_id)
     }
diff --git a/aya/src/programs/xdp.rs b/aya/src/programs/xdp.rs
index 66b32b32..e21dd2f2 100644
--- a/aya/src/programs/xdp.rs
+++ b/aya/src/programs/xdp.rs
@@ -197,10 +197,10 @@ impl Xdp {
         self.data.links.remove(link_id)
     }
 
-    /// Takes ownership of the link referenced by the provided link_id.
+    /// Takes ownership of the link referenced by the provided `link_id`.
     ///
-    /// The link will be detached on `Drop` and the caller is now responsible
-    /// for managing its lifetime.
+    /// The caller takes the responsibility of managing the lifetime of the
+    /// link. When the returned [`XdpLink`] is dropped, the link is detached.
     pub fn take_link(&mut self, link_id: XdpLinkId) -> Result<XdpLink, ProgramError> {
         self.data.take_link(link_id)
     }