[UPDATE] the doxygen in the code to be more verbose

Author: HenraL

vscode/asperheader/src/constants.ts

@@ -2,7 +2,7 @@
  * @file constants.ts
  * @brief Global constants and configuration values for AsperHeader extension
  * @author Henry Letellier
- * @version 1.0.0
+ * @version 1.0.4
  * @date 2025
  * 
  * This module defines all global constants, configuration values, and default settings

vscode/asperheader/src/extension.ts

@@ -1,3 +1,45 @@
+/**
+ * @file extension.ts
+ * @brief Main extension entry point for AsperHeader VS Code extension
+ * @author Henry Letellier
+ * @version 1.0.4
+ * @date 2025
+ * 
+ * This file serves as the primary activation point for the AsperHeader VS Code extension,
+ * providing comprehensive file header management with ASCII art integration, multi-language
+ * support, and automated documentation features. The extension orchestrates various
+ * modules to deliver a cohesive development experience for file organization and
+ * documentation standardization.
+ * 
+ * Key responsibilities include:
+ * - Extension lifecycle management (activation/deactivation)
+ * - Command registration and routing
+ * - Module initialization and dependency injection
+ * - Workspace configuration and state management
+ * - Document save event handling with header refresh
+ * 
+ * The extension integrates multiple specialized modules:
+ * - CommentGenerator: Automated header injection and refresh
+ * - RandomLogo: ASCII art logo selection and display
+ * - Darling: Easter egg functionality with character display
+ * - Watermark: Author watermark management
+ * - MorseTranslator: Text-to-Morse code conversion utilities
+ * - Logger: Dual-channel logging system for development and user feedback
+ * 
+ * @example Extension activation workflow:
+ * ```typescript
+ * // Extension activates automatically when VS Code loads
+ * // Commands become available in Command Palette:
+ * // - "AsperHeader: Hello World"
+ * // - "AsperHeader: Say Hello World"
+ * // - "AsperHeader: Inject Header"
+ * // - "AsperHeader: Refresh Header"
+ * // - "AsperHeader: Display Random Logo"
+ * 
+ * // Headers auto-refresh on file save when configured
+ * ```
+ */
+
 import * as path from "path";
 import * as vscode from 'vscode';
 import { moduleName } from './constants';
@@ -30,6 +72,16 @@ const WATERMARK: Watermark = new Watermark();
 const RANDOM_LOGO: RandomLogo = new RandomLogo();
 
 // --- Helper functions ---
+
+/**
+ * @brief Extracts comprehensive file information from VS Code text editor
+ * @param editor Active VS Code text editor instance
+ * @return Object containing file path, name, extension, and language ID
+ * 
+ * Analyzes the active editor's document to extract metadata used for
+ * header generation and file processing. Essential for context-aware
+ * operations across different file types and languages.
+ */
 function getFileInfo(editor: vscode.TextEditor) {
 	const document = editor.document;
 	const filePath = document.uri.fsPath;
@@ -43,14 +95,21 @@ function getFileInfo(editor: vscode.TextEditor) {
 // --- Command implementations ---
 
 /**
- * Command: Hello World
+ * @brief Displays a simple greeting message from the extension
+ * 
+ * Basic command implementation showing informational notification
+ * to verify extension functionality and user interaction.
  */
 function helloWorldCommand() {
 	vscode.window.showInformationMessage(getMessage("helloWorldGreetingsCommand", moduleName));
 }
 
 /**
- * Command: Say Hello with file info
+ * @brief Inserts greeting message with current file information
+ * 
+ * Advanced hello command that analyzes the active editor and
+ * inserts contextual information including file path, extension,
+ * and language type. Demonstrates file analysis capabilities.
  */
 async function sayHelloWorldCommand() {
 	const editor = vscode.window.activeTextEditor;
@@ -69,7 +128,12 @@ async function sayHelloWorldCommand() {
 }
 
 /**
- * Update checks to avoid concurrency during a save trigger
+ * @brief Thread-safe document update handler for save events
+ * @param document VS Code text document being saved
+ * 
+ * Implements concurrency control to prevent multiple simultaneous
+ * header updates during save operations. Uses WeakSet tracking
+ * to ensure atomic updates and prevent corruption.
  */
 async function updateSaveSafe(document: vscode.TextDocument) {
 	if (updatingDocuments.has(document)) {
@@ -90,7 +154,11 @@ async function updateSaveSafe(document: vscode.TextDocument) {
 }
 
 /**
- * Refresh the name of the cached workspace if any is activated
+ * @brief Updates cached workspace name from VS Code workspace state
+ * 
+ * Analyzes current workspace configuration to extract and cache
+ * the workspace name for use in header generation. Handles both
+ * workspace folders and legacy root path configurations.
  */
 function refreshWorkspaceName() {
 	let workspaceName: string | undefined;
@@ -107,9 +175,21 @@ function refreshWorkspaceName() {
 }
 
 /**
- * Activate extension
+ * @brief Main extension activation entry point
+ * @param context VS Code extension context providing access to extension resources
+ * 
+ * Orchestrates complete extension initialization including:
+ * - Module dependency injection and configuration
+ * - Asset path resolution for templates and resources
+ * - Command registration for user interaction
+ * - Event handler setup for document management
+ * - Logger initialization with installation state
+ * 
+ * Called automatically by VS Code when extension loads or
+ * when activation events are triggered.
  */
 export async function activate(context: vscode.ExtensionContext) {
+	logger.updateInstallationState(context);
 	logger.Gui.debug(`context.extensionPath: ${context.extensionPath}`);
 	const jsonLanguagePath: string = path.join(
 		context.extensionPath,
@@ -160,6 +240,10 @@ export async function activate(context: vscode.ExtensionContext) {
 }
 
 /**
- * Deactivate extension
+ * @brief Extension cleanup and deactivation handler
+ * 
+ * Called when extension is deactivated, disabled, or VS Code closes.
+ * Currently implements graceful shutdown without explicit cleanup
+ * as modules handle their own resource management.
  */
 export function deactivate() { }

vscode/asperheader/src/modules/commentGenerator.ts

@@ -1,13 +1,58 @@
 /**
  * @file commentGenerator.ts
- * @brief Comment generator module for creating file headers with logos and metadata
+ * @brief Comprehensive comment and header generation system for AsperHeader extension
  * @author Henry Letellier
- * @version 1.0.0
+ * @version 1.0.4
  * @date 2025
  * 
- * This module provides functionality to generate and manage file headers with
- * customizable logos, project information, and metadata. It supports multiple
- * comment styles and automatic header refresh on file save.
+ * This module serves as the core engine for generating, injecting, and managing 
+ * file headers with customizable logos, project metadata, and timestamp tracking.
+ * It provides intelligent comment style detection, multi-language support, and
+ * seamless integration with the VS Code workspace environment.
+ * 
+ * Architecture Overview:
+ * - **CommentGenerator**: Main orchestrator class managing header lifecycle
+ * - **Language Detection**: Automatic identification of file types and comment styles
+ * - **Template System**: Flexible header templates with variable substitution  
+ * - **Logo Integration**: Dynamic logo selection from ASCII art collections
+ * - **Metadata Management**: Creation date, modification tracking, and file properties
+ * - **Configuration Integration**: Deep integration with {@link processConfiguration} system
+ * 
+ * Key Dependencies:
+ * - {@link LazyFileLoader}: Lazy loading of language configuration files
+ * - {@link RandomLogo}: ASCII art logo selection and management
+ * - {@link querier}: User interaction and input validation
+ * - {@link logger}: Comprehensive logging and error reporting
+ * - {@link processConfiguration}: Extension configuration and workspace settings
+ * 
+ * Supported Features:
+ * - Multi-line and single-line comment generation
+ * - Language-specific comment syntax adaptation
+ * - Automatic header refresh on file save
+ * - Project name and workspace integration
+ * - Telegraph-style protocol markers for structured headers
+ * - Copyright and authorship attribution
+ * - File description and purpose documentation
+ * 
+ * Integration Points:
+ * This module integrates with the extension's save event handlers, workspace
+ * configuration system, and user interface components to provide seamless
+ * header management throughout the development workflow.
+ * 
+ * @example Basic header injection:
+ * ```typescript
+ * const generator = new CommentGenerator(lazyFileLoader);
+ * generator.updateLogoInstanceRandomiser(randomLogo);
+ * await generator.injectHeader(); // Injects header to active editor
+ * ```
+ * 
+ * @example Automatic refresh setup:
+ * ```typescript
+ * // In extension activation
+ * vscode.workspace.onDidSaveTextDocument(async (document) => {
+ *     await generator.refreshHeader(document);
+ * });
+ * ```
  */
 
 import * as vscode from 'vscode';
@@ -36,19 +81,55 @@ interface CommentStyle {
 }
 
 /**
- * @class CommentGenerator
- * @brief Main class responsible for generating and managing file headers
+ * @class CommentGenerator  
+ * @brief Intelligent file header generation and management system
+ * 
+ * The CommentGenerator class serves as the central orchestrator for all header-related
+ * operations within the AsperHeader extension. It provides comprehensive functionality
+ * for creating, updating, and maintaining file headers with rich metadata, ASCII art
+ * logos, and language-appropriate comment formatting.
  * 
- * This class handles the creation, injection, and updating of file headers with
- * project metadata, logos, creation/modification dates, and other customizable
- * information. It supports multiple programming languages and comment styles.
+ * Core Responsibilities:
+ * - **Header Lifecycle Management**: Creation, injection, refresh, and validation
+ * - **Language Adaptation**: Automatic detection and appropriate comment style selection
+ * - **Template Processing**: Dynamic variable substitution in header templates
+ * - **Logo Integration**: Seamless integration with {@link RandomLogo} for ASCII art
+ * - **Metadata Tracking**: Creation timestamps, modification dates, and file properties
+ * - **User Interaction**: Prompting for missing information and configuration
  * 
- * Key features:
- * - Automatic language detection and comment style selection
- * - Random logo generation from asset collections
- * - Header refresh on file save
- * - Metadata tracking (creation date, last modified, etc.)
- * - Multi-language support through configuration files
+ * Architectural Features:
+ * - **Lazy Loading**: Language configurations loaded on-demand for performance
+ * - **Configuration Integration**: Deep coupling with {@link CodeConfig} settings
+ * - **Error Resilience**: Comprehensive error handling and user feedback
+ * - **Workspace Awareness**: Context-sensitive behavior based on workspace state
+ * - **Multi-Language Support**: Extensible system supporting diverse programming languages
+ * 
+ * Header Structure:
+ * Generated headers follow a structured format including:
+ * - Opening decoration and logo placement
+ * - Project identification and file metadata  
+ * - Creation and modification timestamps
+ * - Description, purpose, and copyright information
+ * - Telegraph protocol markers for structured communication
+ * - Closing decoration and formatting
+ * 
+ * Performance Considerations:
+ * - Language configurations cached after first load
+ * - Header parsing optimized for large files
+ * - Minimal VS Code API calls to reduce overhead
+ * - Efficient string manipulation and template processing
+ * 
+ * @example Advanced usage with configuration:
+ * ```typescript
+ * const generator = new CommentGenerator(configLoader);
+ * generator.updateLogoInstanceRandomiser(logoProvider);
+ * 
+ * // Configure behavior
+ * await generator.refreshHeader(document, {
+ *     forceUpdate: true,
+ *     preserveDescription: false
+ * });
+ * ```
  */
 export class CommentGenerator {
     /** @brief Configuration object containing all extension settings */
@@ -200,8 +281,8 @@ export class CommentGenerator {
                     const extensionsForLang = nodeFileExtensions[langName] ?? [];
                     for (let extIndex = 0; extIndex < extensionsForLang.length; extIndex++) {
                         let dot: string = "";
-                        if (extensionsForLang[extIndex].length >0 && extensionsForLang[extIndex][0] === ".") {
-                            dot=".";
+                        if (extensionsForLang[extIndex].length > 0 && extensionsForLang[extIndex][0] === ".") {
+                            dot = ".";
                         }
                         if (extensionsForLang[extIndex] === `${dot}${this.fileExtension}`) {
                             nodeFound = true;
@@ -215,6 +296,7 @@ export class CommentGenerator {
                 }
             }
 
+            logger.debug(getMessage("arrayNodeContent", `Json[${primaryKey}]`, index, node));
             if (nodeFound) {
                 logger.Gui.info(getMessage("identifiedLanguage", locatedName));
                 logger.info(getMessage("arrayNodeContent", `Json[${primaryKey}]`, index, node));
@@ -223,7 +305,6 @@ export class CommentGenerator {
                 commentStructure.prompt_comment_opening_type = node.prompt_comment_opening_type ?? false;
                 return commentStructure;
             }
-            logger.debug(getMessage("arrayNodeContent", `Json[${primaryKey}]`, index, node));
         }
         logger.error(getMessage("languageNotFound", String(this.languageId), this.fileExtension));
         return commentStructure;