docs: Enhance documentation with detailed comments and descriptions for functions and modules

Author: GeekMasher

src/action.rs

@@ -1,17 +1,26 @@
 #![allow(dead_code)]
+//! Action module for defining and handling the GitHub Action's inputs, outputs, and core functionality
+//!
+//! This module contains the Action struct which represents the GitHub Action and implements
+//! the necessary functionality to process inputs, validate configurations, and manage outputs.
 use std::path::PathBuf;
 
 use anyhow::{Context, Result};
 use ghactions::prelude::*;
 use ghactions_core::repository::reference::RepositoryReference as Repository;
 use ghastoolkit::{CodeQL, CodeQLPack, codeql::CodeQLLanguage};
 
+/// ASCII art banner for the CodeQL Extractor Action
 pub const BANNER: &str = r#"   ___          _        ____  __    __      _     _        _   
   / __\___   __| | ___  /___ \/ /   /__\_  _| |_  /_\   ___| |_ 
  / /  / _ \ / _` |/ _ \//  / / /   /_\ \ \/ / __|//_\\ / __| __|
 / /__| (_) | (_| |  __/ \_/ / /___//__  >  <| |_/  _  \ (__| |_ 
 \____/\___/ \__,_|\___\___,_\____/\__/ /_/\_\\__\_/ \_/\___|\__|"#;
+
+/// Version of the CodeQL Extractor Action, pulled from Cargo.toml
 pub const VERSION: &str = env!("CARGO_PKG_VERSION");
+
+/// Authors of the CodeQL Extractor Action, pulled from Cargo.toml
 pub const AUTHORS: &str = env!("CARGO_PKG_AUTHORS");
 
 /// This action is for 3rd party CodeQL extractors to be used in GitHub Actions
@@ -94,6 +103,13 @@ pub struct Action {
 }
 
 impl Action {
+    /// Returns the working directory for the action
+    ///
+    /// If no working directory is provided, the current directory is used.
+    /// Otherwise, the provided directory is resolved to an absolute path.
+    ///
+    /// # Returns
+    /// - `Result<PathBuf>`: The resolved working directory path
     pub fn working_directory(&self) -> Result<PathBuf> {
         if self.working_directory.is_empty() {
             log::debug!("No working directory provided, using the current directory");
@@ -108,8 +124,13 @@ impl Action {
             ))
     }
 
-    /// Gets the repository to use for the extractor. If the repository is not provided,
-    /// it will use the repository that the action is running in.
+    /// Gets the repository references for the extractors
+    ///
+    /// If no extractor repositories are provided, the current repository is used.
+    /// Otherwise, the provided repositories are parsed into Repository objects.
+    ///
+    /// # Returns
+    /// - `Result<Vec<Repository>>`: A list of parsed repository references
     pub fn extractor_repository(&self) -> Result<Vec<Repository>> {
         if self.extractors.is_empty() {
             log::debug!("No extractor repository provided, using the current repository");
@@ -129,13 +150,19 @@ impl Action {
             .collect::<Vec<Repository>>())
     }
 
+    /// Returns the list of languages to use for CodeQL analysis.
     pub fn languages(&self) -> Vec<CodeQLLanguage> {
         self.languages
             .iter()
             .map(|lang| CodeQLLanguage::from(lang.as_str()))
             .collect()
     }
 
+    /// Returns the directory to use for CodeQL operations.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the directory cannot be created.
     pub fn get_codeql_dir(&self) -> Result<PathBuf> {
         let paths = vec![
             // Local CodeQL directory in the working directory
@@ -162,6 +189,11 @@ impl Action {
         Err(anyhow::anyhow!("Failed to create CodeQL directory",))
     }
 
+    /// Validates the provided languages against the supported CodeQL languages.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if any of the provided languages are not supported.
     pub fn validate_languages(&self, codeql_languages: &Vec<CodeQLLanguage>) -> Result<()> {
         for lang in self.languages() {
             let mut supported = false;
@@ -187,6 +219,9 @@ impl Action {
         Ok(())
     }
 
+    /// Returns the CodeQL version to use.
+    ///
+    /// If the CodeQL version is not provided, it defaults to "latest".
     pub fn codeql_version(&self) -> &str {
         if self.codeql_version.is_empty() {
             log::debug!("No CodeQL version provided, using the latest version");
@@ -195,6 +230,11 @@ impl Action {
         &self.codeql_version
     }
 
+    /// Installs the specified CodeQL packs.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if any of the packs cannot be installed.
     pub async fn install_packs(&self, codeql: &CodeQL) -> Result<()> {
         log::info!("Installing CodeQL Packs");
         for pack in &self.packs {
@@ -227,10 +267,12 @@ impl Action {
         Ok(())
     }
 
+    /// Returns whether attestation is enabled.
     pub fn attestation(&self) -> bool {
         self.attestation
     }
 
+    /// Returns whether empty databases are allowed.
     pub fn allow_empty_database(&self) -> bool {
         self.allow_empty_database
     }
@@ -240,6 +282,12 @@ impl Action {
 mod tests {
     use super::*;
 
+    /// Helper function to create a test Action instance with predefined values
+    ///
+    /// Creates an Action with:
+    /// - A single extractor repository "owner/repo"
+    /// - A single language "iac"
+    /// - Default values for all other fields
     fn action() -> Action {
         Action {
             extractors: vec!["owner/repo".to_string()],
@@ -248,6 +296,11 @@ mod tests {
         }
     }
 
+    /// Test that language validation works correctly
+    ///
+    /// Tests two scenarios:
+    /// 1. When a language is specified that isn't supported by CodeQL (should error)
+    /// 2. When a language is specified that is supported by CodeQL (should pass)
     #[test]
     fn test_validate_languages() {
         let action = action();

src/codeql.rs

@@ -1,7 +1,25 @@
+//! CodeQL installation and management utilities
+//!
+//! This module provides helper functions for downloading and installing CodeQL,
+//! particularly through alternative methods like GitHub CLI when the standard 
+//! installation process fails.
+
 use anyhow::{Context, Result};
 use ghastoolkit::CodeQL;
 
-/// Download the CodeQL CLI using the GitHub CLI
+/// Download and install the CodeQL CLI using the GitHub CLI
+///
+/// This function serves as a fallback installation method when the standard CodeQL 
+/// installation process fails. It uses the GitHub CLI to:
+/// 1. Install the gh-codeql extension
+/// 2. Set the specified CodeQL version
+/// 3. Install the CodeQL stub for command-line access
+///
+/// # Arguments
+/// * `codeql_version` - The version of CodeQL to download (e.g., "latest" or a specific version)
+///
+/// # Returns
+/// * `Result<String>` - Path to the installed CodeQL binary or an error
 pub async fn gh_codeql_download(codeql_version: &str) -> Result<String> {
     log::info!("Downloading CodeQL Extension for GitHub CLI...");
     tokio::process::Command::new("gh")

src/extractors.rs

@@ -4,6 +4,17 @@ use ghactions_core::repository::reference::RepositoryReference as Repository;
 use octocrab::models::repos::{Asset, Release};
 use std::{os::unix::fs::PermissionsExt, path::PathBuf};
 
+/// Fetches a release from a GitHub repository
+///
+/// If the repository reference includes a specific tag, it fetches that release.
+/// Otherwise, it fetches the latest release.
+///
+/// # Arguments
+/// * `client` - The Octocrab client to use for API requests
+/// * `repository` - The repository reference containing owner, name, and optional tag
+///
+/// # Returns
+/// * `Result<Release>` - The fetched release or an error
 async fn fetch_releases(client: &octocrab::Octocrab, repository: &Repository) -> Result<Release> {
     let release = if let Some(rel) = &repository.reference {
         log::info!("Fetching release by tag: {}", rel);
@@ -164,7 +175,16 @@ pub async fn fetch_extractor(
 
 /// Update the SARIF file with the extractor information (CodeQL ${language})
 ///
-///  Update only the `runs.0.tool.driver` section of the SARIF file
+/// Updates only the `runs.0.tool.driver` section of the SARIF file to include 
+/// information about which extractor was used. This helps in distinguishing
+/// results from different CodeQL extractors when analyzing multiple languages.
+///
+/// # Arguments
+/// * `path` - Path to the SARIF file that needs to be updated
+/// * `extractor` - Name of the extractor to be added to the SARIF metadata
+///
+/// # Returns
+/// * `Result<()>` - Success or an error if the SARIF file couldn't be updated
 pub fn update_sarif(path: &PathBuf, extractor: String) -> Result<()> {
     let sarif_content =
         std::fs::read_to_string(path).context(format!("Failed to read SARIF file: {:?}", path))?;
@@ -194,7 +214,16 @@ pub fn update_sarif(path: &PathBuf, extractor: String) -> Result<()> {
     Ok(())
 }
 
-/// Update the permissions for tool scripts (*.sh) and the extractor (extractor)
+/// Update the permissions for tool scripts (*.sh) and the extractor executables
+///
+/// Makes shell scripts and extractor binaries executable by setting appropriate permissions.
+/// Looks for tools in standard locations for Linux (linux64/extractor) and macOS (osx64/extractor).
+///
+/// # Arguments
+/// * `path` - The base path where tools are located
+///
+/// # Returns
+/// * `Result<()>` - Success or an error if permissions couldn't be set
 fn update_tools_permisisons(path: &PathBuf) -> Result<()> {
     let tools_path = path.join("tools");
     log::info!("Tools :: {tools_path:?}");
@@ -226,7 +255,16 @@ fn update_tools_permisisons(path: &PathBuf) -> Result<()> {
     Ok(())
 }
 
-/// Sets the file permissions to be executable
+/// Sets the file permissions to be executable (read and execute for all users)
+///
+/// Sets the permissions to 0o555 (r-xr-xr-x) which allows reading and 
+/// execution by all users, but no write permissions.
+///
+/// # Arguments
+/// * `path` - The path to the file whose permissions should be set
+///
+/// # Returns
+/// * `Result<()>` - Success or an error if permissions couldn't be set
 fn set_permissions(path: &PathBuf) -> Result<()> {
     log::info!("Setting permissions for :: {:?}", path);
     let perms = std::fs::Permissions::from_mode(0o555);

src/main.rs

@@ -1,3 +1,7 @@
+//! Main module for the CodeQL Extractor Action
+//! 
+//! This module contains the main function and orchestrates the entire workflow
+//! for setting up CodeQL, fetching and configuring extractors, and running analyses.
 use anyhow::{Context, Result};
 use ghactions::{ActionTrait, group, groupend};
 use ghactions_core::RepositoryReference;
@@ -13,6 +17,15 @@ use action::{AUTHORS, Action, BANNER, VERSION};
 
 use crate::codeql::gh_codeql_download;
 
+/// Main function that drives the CodeQL Extractor Action workflow
+///
+/// This function:
+/// 1. Initializes the Action
+/// 2. Sets up CodeQL
+/// 3. Fetches and configures the extractors
+/// 4. Creates databases for each language
+/// 5. Runs analyses on the databases
+/// 6. Processes and updates the SARIF results
 #[tokio::main]
 async fn main() -> Result<()> {
     let mut action = Action::init()?;