docs: added documentation, enforced documentation

src/package_info.rs

@@ -93,6 +93,7 @@ fn get_series_from_file(path: &str) -> Result<Vec<String>, Box<dyn Error>> {
     parse_series_csv(&content)
 }
 
+/// Obtain a list of series from a distribution
 pub async fn get_dist_series(dist: &str) -> Result<Vec<String>, Box<dyn Error>> {
     if Path::new(format!("/usr/share/distro-info/{dist}.csv").as_str()).exists() {
         get_series_from_file(format!("/usr/share/distro-info/{dist}.csv").as_str())
@@ -105,6 +106,7 @@ pub async fn get_dist_series(dist: &str) -> Result<Vec<String>, Box<dyn Error>>
     }
 }
 
+/// Obtain the distribution (eg. debian, ubuntu) from a distribution series (eg. noble, bookworm)
 pub async fn get_dist_from_series(series: &str) -> Result<String, Box<dyn Error>> {
     let debian_series = get_dist_series("debian").await?;
     if debian_series.contains(&series.to_string()) {
@@ -117,34 +119,55 @@ pub async fn get_dist_from_series(series: &str) -> Result<String, Box<dyn Error>
     Err(format!("Unknown series: {}", series).into())
 }
 
+/// A File used in a source package
 #[derive(Debug, Clone)]
 pub struct FileEntry {
+    /// Name of the file
     pub name: String,
+    /// Size of the file
     pub size: u64,
+    /// SHA256 hash for the file
     pub sha256: String,
 }
 
+/// A package 'stanza' as found is 'Sources.gz' files, containing basic information about a source package
 #[derive(Debug)]
 pub struct PackageStanza {
+    /// Name of the package
     pub package: String,
+    /// Version number for the package
     pub version: String,
+    /// Directory field in the stanza
     pub directory: String,
+    /// Source package format (e.g. '3.0 (quilt)')
     pub format: String,
+    /// Vcs-Git field in the stanza
     pub vcs_git: Option<String>,
+    /// Vcs-Browser field in the stanza
     pub vcs_browser: Option<String>,
+    /// Files present in the source package
     pub files: Vec<FileEntry>,
 }
 
+/// Source package information
 #[derive(Debug)]
 pub struct PackageInfo {
-    pub dist: String,
-    pub series: String,
+    /// Source 'stanza' for the package, containing basic information
     pub stanza: PackageStanza,
+    /// Distribution for the package
+    pub dist: String,
+    /// Distribution series for the package
+    pub series: String,
+    /// Preferred VCS for the source package
+    ///
+    /// Should be Launchpad on Ubuntu, and Salsa on Debian
     pub preferred_vcs: Option<String>,
+    /// URL for the files of the source package
     pub archive_url: String,
 }
 
 impl PackageInfo {
+    /// Returns true if the package is a Debian native package (no orig)
     pub fn is_native(&self) -> bool {
         self.stanza.format.contains("(native)")
     }
@@ -175,9 +198,7 @@ fn get_base_url(dist: &str) -> &str {
     }
 }
 
-/*
-* Obtain the URL for the 'Release' file of a distribution series
-*/
+/// Obtain the URL for the 'Release' file of a distribution series
 fn get_release_url(base_url: &str, series: &str, pocket: &str) -> String {
     let pocket_full = if pocket.is_empty() {
         String::new()
@@ -187,9 +208,7 @@ fn get_release_url(base_url: &str, series: &str, pocket: &str) -> String {
     format!("{base_url}/dists/{series}{pocket_full}/Release")
 }
 
-/*
-* Obtain the components of a distribution series by parsing the 'Release' file
-*/
+/// Obtain the components of a distribution series by parsing the 'Release' file
 async fn get_components(
     base_url: &str,
     series: &str,
@@ -296,10 +315,8 @@ impl Iterator for DebianSources {
     }
 }
 
-/*
-* Parse a 'Sources.gz' debian package file data, to look for a target package and
-* return the data for that package stanza
-*/
+/// Parse a 'Sources.gz' debian package file data, to look for a target package and
+/// return the data for that package stanza
 fn parse_sources(
     data: &[u8],
     target_package: &str,
@@ -314,6 +331,7 @@ fn parse_sources(
     }))
 }
 
+/// Get package information from a package, distribution series, and pocket
 pub async fn get(
     package_name: &str,
     series: &str,
@@ -387,6 +405,7 @@ pub async fn get(
     .into())
 }
 
+/// Try to find package information in a distribution, trying all series and pockets
 pub async fn find_package(
     package_name: &str,
     dist: &str,