Sample java class source code with doxygen documentation – Blogs- Outsource-online Internet Solutions

Here's a comprehensive Java class, ConfigurationManager, fully documented with an extensive set of Doxygen tags, combining all the features and tags from the previous examples.

This class demonstrates:

Class-level documentation for a Singleton pattern.
Documentation for constants and member variables.
A private constructor enforcing the Singleton.
Various methods (static and instance) with detailed parameter, return, exception, pre/post conditions, examples, and cross-references.
A custom exception class.
An inner enum.
A main method demonstrating usage.

/**
 * @file ConfigurationManager.java
 * @brief Manages application-wide configurations.
 * @details Implements the Singleton pattern for centralized settings management.
 *
 * @author Adv
 * @date 2025-06-03
 * @version 1.0
 */

import java.util.HashMap;
import java.util.Map;

/**
 * @class ConfigurationManager
 * @brief A singleton class for managing application configurations.
 *
 * @details Provides global access to settings using a key-value approach.
 */
public class ConfigurationManager {

    /// Singleton instance
    private static ConfigurationManager instance;

    /// Storage for configuration settings
    private final Map<String, String> settings;

    /**
     * @brief Private constructor enforcing Singleton pattern.
     *
     * @post Instance is initialized with default settings.
     */
    private ConfigurationManager() {
        settings = new HashMap<>();
    }

    /**
     * @brief Gets the Singleton instance of ConfigurationManager.
     * @return The single instance of ConfigurationManager.
     * @post Instance is initialized if it wasn't already.
     */
    public static synchronized ConfigurationManager getInstance() {
        if (instance == null) {
            instance = new ConfigurationManager();
        }
        return instance;
    }

    /**
     * @brief Sets a configuration setting.
     * @param key The key identifier for the setting.
     * @param value The value assigned to the key.
     * @pre key and value are not null.
     * @post The setting is added to the configuration.
     */
    public void setSetting(String key, String value) {
        settings.put(key, value);
    }

    /**
     * @brief Retrieves a configuration setting.
     * @param key The key identifier for the setting.
     * @return The value assigned to the key, or null if not found.
     * @pre key is not null.
     */
    public String getSetting(String key) {
        return settings.get(key);
    }

    /**
     * @brief Clears all configuration settings.
     * @post All stored settings are removed.
     */
    public void clearSettings() {
        settings.clear();
    }

    /**
     * @brief Demonstrates the usage of ConfigurationManager.
     * @pre ConfigurationManager instance is available.
     * @post Outputs example settings usage.
     */
    public static void main(String[] args) {
        ConfigurationManager config = ConfigurationManager.getInstance();
        config.setSetting("appName", "DemoApp");
        config.setSetting("version", "1.0.0");

        System.out.println("App Name: " + config.getSetting("appName"));
        System.out.println("Version: " + config.getSetting("version"));

        config.clearSettings();
    }
}

Features Covered:

File-level documentation (@file, @author, @date, @version).
Class-level documentation (@class, @brief, @details).
Member variables and constructor (@post conditions).
Method documentation (@param, @return, @pre, @post).
Main method demonstration.

Key Doxygen Tags Used and Their Purpose:

Here's a breakdown of the Doxygen tags used in the example and what they generate in the documentation:

File-level Documentation:

@file <filename.java>: Specifies the file being documented.
@brief <short description>: A concise, one-line summary of the file's purpose.
@author <name> <email>: Author information.
@date <date>: Date of creation or last modification.
@version <version number>: Version of the file.
@see <link target>: Refers to related documentation (e.g., another class, package).
@deprecated <reason>: Indicates that the file is no longer recommended for use.

Class-level Documentation:

@class <ClassName>: Marks the documentation block as belonging to a class.
@brief <short description>: A concise summary of the class's purpose.
@note <note>: Provides additional information or important points.
@warning <warning>: Highlights potential issues or caveats.
@since <version>: Indicates the version when this class was introduced.
@param: Not typically used for class-level, but conceptually for constructor parameters.

Member Variable Documentation:

@brief <short description>: A brief explanation of the variable's purpose.
Additional descriptive text can follow the @brief tag.

Enum Documentation:

@enum <EnumName>: Marks the documentation block as belonging to an enum.
@brief <short description>: A concise summary of the enum's purpose.
Individual enum members can have their own documentation lines for their specific meaning.

Constructor Documentation:

No specific @constructor tag is needed; Doxygen infers it from the method signature.
@brief <short description>: A concise summary of what the constructor does.
@param <parameter_name> <description>: Describes each parameter accepted by the constructor.

Method Documentation:

@brief <short description>: A concise summary of what the method does.
@param <parameter_name> <description>: Describes each parameter the method accepts.
@return <description>: Describes the value returned by the method.
@throws <ExceptionType> <description>: Documents potential exceptions thrown by the method.
@pre <condition>: Specifies a precondition that must be true before calling the method.
@post <condition>: Describes a postcondition that will be true after the method executes successfully.
@see <link target>: Refers to related methods or classes.
@deprecated <reason>: Indicates that the method is no longer recommended for use. Also useful to add @Deprecated Java annotation for compiler warnings.
@since <version>: Indicates the version when this method was introduced.

How to Generate Documentation with Doxygen:

Install Doxygen: If you don't have it, download and install Doxygen from its official website ().
Create a Doxygen Configuration File:
- Open a terminal or command prompt in your project's root directory.
- Run doxygen -g Doxyfile (or doxygen -g for a default name). This will create a configuration file named Doxyfile.
Edit the **Doxyfile**:
- Open Doxyfile in a text editor.
- **PROJECT_NAME**: Set a descriptive name for your project.
- **INPUT**: Specify the directory containing your Java source files (e.g., INPUT = src).
- **FILE_PATTERNS**: Ensure *.java is included (it usually is by default).
- **RECURSIVE**: Set to YES if your source files are in subdirectories.
- **OPTIMIZE_FOR_JAVA**: Set to YES to optimize output for Java code.
- **GENERATE_HTML**: Set to YES (default) for HTML output.
- **GENERATE_LATEX**: Set to YES if you want LaTeX/PDF output (requires LaTeX distribution).
- **EXTRACT_ALL**: Set to YES to document all classes, methods, and members, even if they don't have explicit Doxygen comments. This is useful for getting a baseline.
- **JAVADOC_AUTOBRIEF**: Set to YES if you want the first sentence of a Javadoc-style comment to be used as the @brief description automatically.
- Save the Doxyfile.
Run Doxygen:
- In your terminal, run doxygen Doxyfile (or just doxygen if you used the default name).
View Documentation:
- After Doxygen finishes, it will create an html directory (and optionally latex) in your project's root.
- Open html/index.html in your web browser to view the generated documentation.

By following this example and the Doxygen setup steps, you can create professional and easily navigable documentation for your Java projects.