docs: complete Backend trait

crates/pacdef_core/src/backend/backend_trait.rs

@@ -11,20 +11,44 @@ use crate::{Group, Package};
 pub(in crate::backend) type Switches = &'static [&'static str];
 pub(in crate::backend) type Text = &'static str;
 
+/// The trait of a struct that is used as a backend.
 pub trait Backend: Debug {
+    /// Return the actual binary. Iff the backend supports different
+    /// binaries, you will need to overwrite this implementation to return
+    /// the binary that was loaded at runtime. See
+    /// [`Backend::get_binary_default()`].
     fn get_binary(&self) -> Text {
         self.get_binary_default()
     }
+
+    /// Return the default binary as defined in the constant of the module.
+    /// See [`Backend::get_binary()`].
     fn get_binary_default(&self) -> Text;
+
+    /// Get the name of the section in the group files.
     fn get_section(&self) -> Text;
 
+    /// Get CLI switches for the package manager to show information for
+    /// packages.
     fn get_switches_info(&self) -> Switches;
+
+    /// Get CLI switches for the package manager to install packages.
     fn get_switches_install(&self) -> Switches;
+
+    /// Get CLI switches for the package manager to remove packages.
     fn get_switches_remove(&self) -> Switches;
+
+    /// Get CLI switches for the package manager to mark packages as
+    /// dependency. This is not supported by all package managers. See
+    /// [`Backend::supports_as_dependency`].
     fn get_switches_make_dependency(&self) -> Switches;
 
+    /// Load all packages from a set of groups. The backend will visit all groups,
+    /// find its own section, and clone all packages into its own struct.
     fn load(&mut self, groups: &HashSet<Group>);
 
+    /// Get all managed packages for this backend, i.e. all packages
+    /// under the corresponding section in all group files.
     fn get_managed_packages(&self) -> &HashSet<Package>;
 
     /// Get all packages that are installed in the system.
@@ -33,6 +57,8 @@ pub trait Backend: Debug {
     /// Get all packages that were installed in the system explicitly.
     fn get_explicitly_installed_packages(&self) -> Result<HashSet<Package>>;
 
+    /// Assign each of the packages to an individual group by editing the
+    /// group files.
     fn assign_group(&self, to_assign: Vec<(Package, Rc<Group>)>) -> Result<()> {
         let group_package_map = get_group_packages_map(to_assign);
         let section_header = format!("[{}]", self.get_section());
@@ -55,6 +81,8 @@ pub trait Backend: Debug {
             .with_context(|| format!("running command {cmd:?}"))
     }
 
+    /// Mark the packages as non-explicit / dependency using the underlying
+    /// package manager.
     fn make_dependency(&self, packages: &[Package]) -> Result<ExitStatus> {
         let mut cmd = Command::new(self.get_binary());
         cmd.args(self.get_switches_make_dependency());
@@ -76,7 +104,7 @@ pub trait Backend: Debug {
             .with_context(|| format!("running command [{cmd:?}]"))
     }
 
-    /// extract packages from its own section as read from group files
+    /// TODO remove.
     fn extract_packages_from_group_file_content(&self, content: &str) -> HashSet<Package> {
         content
             .lines()
@@ -88,6 +116,7 @@ pub trait Backend: Debug {
             .collect()
     }
 
+    /// Get missing packages, sorted alphabetically.
     fn get_missing_packages_sorted(&self) -> Result<Vec<Package>> {
         let installed = self
             .get_all_installed_packages()
@@ -98,6 +127,7 @@ pub trait Backend: Debug {
         Ok(diff)
     }
 
+    /// TODO remove
     fn add_packages(&mut self, packages: HashSet<Package>);
 
     /// Show information from package manager for package.
@@ -109,6 +139,7 @@ pub trait Backend: Debug {
             .with_context(|| format!("running command {cmd:?}"))
     }
 
+    /// Get unmanaged packages, sorted alphabetically.
     fn get_unmanaged_packages_sorted(&self) -> Result<Vec<Package>> {
         let installed = self
             .get_explicitly_installed_packages()
@@ -119,8 +150,10 @@ pub trait Backend: Debug {
         Ok(diff)
     }
 
+    /// Return a mutable reference to self as `Any`. Required for downcasting.
     fn as_any_mut(&mut self) -> &mut dyn Any;
 
+    /// Whether the underlying package manager supports dependency packages.
     fn supports_as_dependency(&self) -> bool;
 }