From 2972d462a505aaba8d9e40ddf2c6110e497283db Mon Sep 17 00:00:00 2001
From: Andre Fredette <afredette@redhat.com>
Date: Thu, 22 Dec 2022 07:51:35 -0500
Subject: [PATCH] Address review comments

- Rename `new_tc_link` to `attached`
- Simplified example for `attached`

The following was not requested in reviews:
- Moved example from `SchedClassifierLink` tor
  `SchedClassifierLink::attached' since we're only showing an
  example of that one method

Signed-off-by: Andre Fredette <afredette@redhat.com>
---
 aya/src/programs/tc.rs | 69 +++++++++++++-----------------------------
 1 file changed, 21 insertions(+), 48 deletions(-)

diff --git a/aya/src/programs/tc.rs b/aya/src/programs/tc.rs
index 4d021489..7bf536e7 100644
--- a/aya/src/programs/tc.rs
+++ b/aya/src/programs/tc.rs
@@ -229,54 +229,7 @@ define_link_wrapper!(
 );
 
 /// [`SchedClassifierLink`] is the link type used by [`SchedClassifier`] programs.
-///
-/// # Examples
-///
-/// ```no_run
-/// # #[derive(Debug, thiserror::Error)]
-/// # enum Error {
-/// #     #[error(transparent)]
-/// #     IO(#[from] std::io::Error),
-/// #     #[error(transparent)]
-/// #     Map(#[from] aya::maps::MapError),
-/// #     #[error(transparent)]
-/// #     Program(#[from] aya::programs::ProgramError),
-/// #     #[error(transparent)]
-/// #     Bpf(#[from] aya::BpfError)
-/// # }
-/// # let mut bpf = aya::Bpf::load(&[])?;
-/// # tc::qdisc_add_clsact("eth0")?;
-/// # let prog: &mut SchedClassifier = bpf.program_mut("redirect_ingress").unwrap().try_into()?;
-/// # prog.load()?;
-/// #
-/// # use aya::programs::tc::{SchedClassifierLink};
-/// # use aya::programs::{tc, Link, SchedClassifier, TcAttachType};
-/// # use std::mem;
-/// let tc_link_id = prog.attach("eth0", TcAttachType::Ingress)?;
-///
-/// let tc_link = prog.take_link(tc_link_id)?;
-///
-/// // The priority and handle assigned during attach can be accessed as follows:
-/// let priority = tc_link.priority();
-/// let handle = tc_link.handle();
-///
-/// // The following call "forgets" about tc_link so that it is not detached on drop.
-///  mem::forget(tc_link);
-///
-/// // The link can be re-instantiated and detached as shown below.
-/// let new_tc_link = SchedClassifierLink::new_tc_link(
-///     "eth0",
-///     TcAttachType::Ingress,
-///     priority,
-///     handle,
-/// )?;
-/// new_tc_link.detach()?;
-///
-/// # Ok::<(), Error>(())
-/// ```
 impl SchedClassifierLink {
-    /// Creates a new link from the provided values.
-    ///
     /// This API is used to construct a [`SchedClassifierLink`] where the `if_name`, `attach_type`,
     /// `priority` and `handle` are already known. This may have been found from a link created by
     /// [SchedClassifier::attach], the output of the `tc filter` command or from the output of
@@ -288,7 +241,27 @@ impl SchedClassifierLink {
     /// # Errors
     /// - If a program is not attached with the provided parameters, calls to
     ///   [`SchedClassifierLink::detach`] will return a [`TcError::NetlinkError`]
-    pub fn new_tc_link(
+    ///
+    /// # Examples
+    /// ```no_run
+    /// # use aya::programs::tc::SchedClassifierLink;
+    /// # use aya::programs::TcAttachType;
+    /// # #[derive(Debug, thiserror::Error)]
+    /// # enum Error {
+    /// #     #[error(transparent)]
+    /// #     IO(#[from] std::io::Error),
+    /// # }
+    /// # fn read_persisted_link_details() -> (String, TcAttachType, u16, u32) {
+    /// #     ("eth0".to_string(), TcAttachType::Ingress, 50, 1)
+    /// # }
+    /// // Get the link parameters from some external source. Where and how the parameters are
+    /// // persisted is up to your application.
+    /// let (if_name, attach_type, priority, handle) = read_persisted_link_details();
+    /// let new_tc_link = SchedClassifierLink::attached(&if_name, attach_type, priority, handle)?;
+    ///
+    /// # Ok::<(), Error>(())
+    /// ```
+    pub fn attached(
         if_name: &str,
         attach_type: TcAttachType,
         priority: u16,