From b5689cfc724980e4693affe58ffd0348e794ef98 Mon Sep 17 00:00:00 2001
From: Stefano Fontana <stefano.fontana.2000@gmail.com>
Date: Sat, 14 Dec 2024 18:23:08 +0100
Subject: [PATCH] documentation

---
 crates/typst-kit/src/package_downloads/git.rs | 15 +++++++++++++
 .../typst-kit/src/package_downloads/http.rs   | 13 +++++++++++
 crates/typst-kit/src/package_downloads/mod.rs | 22 +++++++++++++++++++
 3 files changed, 50 insertions(+)

diff --git a/crates/typst-kit/src/package_downloads/git.rs b/crates/typst-kit/src/package_downloads/git.rs
index d92544e7..5ca3a5c4 100644
--- a/crates/typst-kit/src/package_downloads/git.rs
+++ b/crates/typst-kit/src/package_downloads/git.rs
@@ -68,6 +68,21 @@ impl GitDownloader {
         Ok(())
     }
 
+    /// Parses the namespace of the package into the correct registry and namespace.
+    /// The namespace format is the following:
+    ///
+    /// @git:<git host and user>
+    ///
+    /// The final repository cloned will be formed by the git host and the repository name
+    /// with the adequate extension, checking out to the tag specified by the version in the format
+    /// v<major>.<minor>.<patch>
+    ///
+    /// For example, the package
+    /// @git:git@github.com:typst/package:0.1.0
+    /// will result in the cloning of the repository git@github.com:typst/package.git
+    /// and the checkout and detached head state at tag v0.1.0
+    ///
+    /// NOTE: no index download is possible.
     fn parse_namespace(ns: &str, name: &str) -> Result<String, EcoString> {
 
         let mut parts = ns.splitn(2, ":");
diff --git a/crates/typst-kit/src/package_downloads/http.rs b/crates/typst-kit/src/package_downloads/http.rs
index a1cb71df..413698f9 100644
--- a/crates/typst-kit/src/package_downloads/http.rs
+++ b/crates/typst-kit/src/package_downloads/http.rs
@@ -120,6 +120,19 @@ impl HttpDownloader {
         Ok(RemoteReader::from_response(response, progress).download()?)
     }
 
+    /// Parses the namespace of the package into the correct registry and namespace.
+    /// The namespace format is the following:
+    ///
+    /// @http[s]:<registry host>:<namespace>/package-name>:package-version
+    ///
+    /// resulting in the package location to be resolved as
+    /// http[s]://<registry host>/<namespace>/<package-name>-<package-version>.tar.gz
+    ///
+    /// and the index to be resolved as
+    /// http[s]://<registry host>/<namespace>/index.json
+    ///
+    /// NOTE: preview namespace is treated as the namespace formed as
+    /// @https:packages.typst.org:preview/package-name>:package-version
     fn parse_namespace(ns: &str) -> Result<(String, String), EcoString> {
         if ns.eq(DEFAULT_NAMESPACE) {
             return Ok((DEFAULT_REGISTRY.to_string(), DEFAULT_NAMESPACE.to_string()))
diff --git a/crates/typst-kit/src/package_downloads/mod.rs b/crates/typst-kit/src/package_downloads/mod.rs
index cf7ef7a1..56c87591 100644
--- a/crates/typst-kit/src/package_downloads/mod.rs
+++ b/crates/typst-kit/src/package_downloads/mod.rs
@@ -10,15 +10,23 @@ use crate::package_downloads::git::GitDownloader;
 /// The public namespace in the default Typst registry.
 pub const DEFAULT_NAMESPACE: &str = "preview";
 
+/*========BEGIN DOWNLOAD METHODS DECLARATION=========*/
 #[cfg(feature = "downloads_http")]
 mod http;
 
 #[cfg(feature = "downloads_git")]
 mod git;
+/*========END DOWNLOAD METHODS DECLARATION===========*/
 
+/// Trait abstraction for package a downloader.
 pub trait PackageDownloader : Debug + Sync + Send {
+
+    /// Download the repository index and returns the
+    /// list of PackageInfo elements contained in it.
     fn download_index(&self, spec: &VersionlessPackageSpec) -> Result<Vec<PackageInfo>, EcoString>;
 
+    /// Download a package from a remote repository/registry
+    /// and writes it in the file system cache directory
     fn download(&self, spec: &PackageSpec, package_dir: &Path, progress: &mut dyn Progress) -> PackageResult<()>;
 }
 
@@ -48,13 +56,18 @@ pub trait Progress {
     fn print_finish(&mut self, state: &DownloadState);
 }
 
+/// The downloader object used for downloading packages
 #[derive(Debug)]
 pub struct Downloader{
+    ///List of all available downloaders which can be instantiated at runtime
     http_downloader: Option<Box<dyn PackageDownloader>>,
     git_downloader: Option<Box<dyn PackageDownloader>>,
 }
 
+
 impl Downloader {
+    /// Construct the Downloader object instantiating all the available methods.
+    /// The methods can be compile-time selected by features.
     pub fn new(cert: Option<PathBuf>) -> Self {
         Self {
             http_downloader: Self::make_http_downloader(cert.clone()),
@@ -62,6 +75,7 @@ impl Downloader {
         }
     }
 
+    /// Creation function for the HTTP(S) download method
     fn make_http_downloader(cert: Option<PathBuf>) -> Option<Box<dyn PackageDownloader>>{
         #[cfg(not(feature = "downloads_http"))]
         { None }
@@ -76,6 +90,7 @@ impl Downloader {
         }
     }
 
+    /// Creation function for the GIT clone method
     fn make_git_downloader(_cert: Option<PathBuf>) -> Option<Box<dyn PackageDownloader>>{
         #[cfg(not(feature = "downloads_git"))]
         { None }
@@ -86,6 +101,13 @@ impl Downloader {
         }
     }
 
+    /// Returns the correct downloader in function of the package namespace.
+    /// The remote location of a package is encoded in its namespace in the form
+    /// @<source type>:<source path>
+    ///
+    /// It's the downloader instance's job to parse the source path in any substructure.
+    ///
+    /// NOTE: Treating @preview as a special case of the https downloader.
     fn get_downloader(&self, ns: &str) -> Result<&Box<dyn PackageDownloader>, PackageError> {
         let download_type = ns.splitn(2, ":").next();