--- name: doxygen-javadoc description: Documentation generation for C, C++, and Java codebases using Doxygen and Javadoc. Extract API documentation from source code, generate cross-references, call graphs, and comprehensive technical documentation. allowed-tools: Read, Write, Edit, Bash, Glob, Grep backlog-id: SK-015 metadata: author: babysitter-sdk version: "1.0.0" --- # Doxygen/Javadoc Skill Generate comprehensive API documentation for C, C++, Java, and other languages using Doxygen and Javadoc with cross-references, call graphs, and coverage analysis. ## Capabilities - Configure Doxygen for C/C++/Java projects - Generate Javadoc for Java codebases - Create cross-reference documentation - Generate call graphs and dependency visualizations - Analyze documentation coverage - Support custom tag definitions - Multiple output formats (HTML, LaTeX, PDF, XML) - Integrate with build systems (CMake, Maven, Gradle) ## Usage Invoke this skill when you need to: - Document C/C++ libraries and applications - Generate Java API documentation - Create reference documentation with diagrams - Set up automated documentation builds - Analyze code structure and dependencies ## Inputs | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | projectPath | string | Yes | Root path of the project | | tool | string | No | doxygen or javadoc (auto-detected) | | sourceDir | string | No | Source directory (default: src) | | outputDir | string | No | Output directory (default: docs) | | outputFormat | array | No | html, latex, pdf, xml, man | | includeGraphs | boolean | No | Generate call/dependency graphs | | configFile | string | No | Existing Doxyfile or pom.xml path | | coverageReport | boolean | No | Generate coverage analysis | ### Input Example ```json { "projectPath": "./mylib", "tool": "doxygen", "sourceDir": "src", "outputDir": "docs/api", "outputFormat": ["html", "xml"], "includeGraphs": true, "coverageReport": true } ``` ## Output Structure ### Doxygen Output ``` docs/api/ ├── html/ │ ├── index.html # Main documentation page │ ├── annotated.html # Class/struct list │ ├── files.html # File list │ ├── modules.html # Module grouping │ ├── namespaces.html # Namespace documentation │ ├── hierarchy.html # Class hierarchy │ ├── class_*.html # Individual class pages │ ├── struct_*.html # Struct documentation │ ├── group__*.html # Module documentation │ ├── *_8h.html # Header file documentation │ └── search/ # Search index ├── xml/ │ ├── index.xml # XML index │ ├── class_*.xml # Class XML │ └── doxygen-layout.xml # Layout configuration ├── latex/ # LaTeX output (if enabled) └── coverage.json # Documentation coverage ``` ### Javadoc Output ``` docs/api/ ├── index.html # Package overview ├── overview-summary.html # Overview page ├── allclasses-index.html # Class index ├── allpackages-index.html # Package index ├── com/ │ └── example/ │ └── package/ │ ├── package-summary.html │ ├── ClassName.html │ └── ... ├── element-list # Package list └── member-search-index.js # Search data ``` ## Doxygen Documentation Patterns ### File Header ```cpp /** * @file database.h * @brief Database connection and query utilities. * * This module provides thread-safe database connection pooling * and query execution with automatic retry logic. * * @author Development Team * @date 2026-01-24 * @version 1.0.0 * * @copyright Copyright (c) 2026, Company Inc. */ ``` ### Class Documentation ```cpp /** * @class ConnectionPool * @brief Thread-safe database connection pool. * * Manages a pool of database connections with configurable * minimum and maximum sizes. Connections are automatically * validated before use. * * @tparam Connection The connection type to pool * * @note This class is thread-safe. * @warning Do not exceed maxConnections in high-load scenarios. * * @see Connection * @see PoolConfig * * @code{.cpp} * ConnectionPool pool(config); * auto conn = pool.acquire(); * conn->execute("SELECT * FROM users"); * pool.release(conn); * @endcode */ template class ConnectionPool { public: /** * @brief Creates a new connection pool. * * @param config Pool configuration parameters * @throws ConfigurationError If config is invalid * * @pre config.maxConnections > 0 * @post Pool is initialized with minConnections */ explicit ConnectionPool(const PoolConfig& config); /** * @brief Acquires a connection from the pool. * * Blocks until a connection is available or timeout expires. * * @param timeout Maximum wait time in milliseconds * @return Shared pointer to the acquired connection * @throws TimeoutError If no connection available within timeout * * @par Thread Safety * This method is thread-safe. */ std::shared_ptr acquire(int timeout = 30000); /** * @brief Releases a connection back to the pool. * * @param conn The connection to release * @retval true Connection successfully returned * @retval false Connection was invalid or pool is closed */ bool release(std::shared_ptr conn); }; ``` ### Function Documentation ```cpp /** * @brief Executes a SQL query with parameter binding. * * @param[in] query The SQL query string with placeholders * @param[in] params Parameter values to bind * @param[out] results Query results (if SELECT) * * @return Number of affected rows (for INSERT/UPDATE/DELETE) * * @throws QueryError If query execution fails * @throws ConnectionError If database connection is lost * * @par Example * @code{.cpp} * std::vector params = {"John", "25"}; * ResultSet results; * int affected = executeQuery( * "SELECT * FROM users WHERE name = ? AND age > ?", * params, * results * ); * @endcode * * @par Performance * Query preparation is cached for repeated executions. * * @todo Add support for batch parameter binding * @bug Large result sets may cause memory issues (see #123) * * @since 1.0.0 * @deprecated Use PreparedStatement::execute() instead */ int executeQuery( const std::string& query, const std::vector& params, ResultSet& results ); ``` ### Module/Group Documentation ```cpp /** * @defgroup Database Database Module * @brief Database connectivity and operations. * * This module provides database abstraction layer with support * for multiple database backends. * * @{ */ /** * @defgroup Database_Connection Connection Management * @brief Connection pooling and lifecycle. */ /** * @defgroup Database_Query Query Execution * @brief Query building and execution. */ /** @} */ // end of Database group ``` ## Javadoc Documentation Patterns ### Package Documentation (package-info.java) ```java /** * Database connectivity and query utilities. * *

This package provides thread-safe database operations with * connection pooling and automatic retry logic.

* *

Usage Example

* 
{@code
 * ConnectionPool pool = new ConnectionPool.Builder()
 *     .maxConnections(10)
 *     .timeout(Duration.ofSeconds(30))
 *     .build();
 *
 * try (Connection conn = pool.acquire()) {
 *     ResultSet rs = conn.executeQuery("SELECT * FROM users");
 * }
 * }
* * @author Development Team * @version 1.0.0 * @since 1.0.0 * @see com.example.database.ConnectionPool */ package com.example.database; ``` ### Class Documentation ```java /** * Thread-safe database connection pool. * *

Manages a pool of database connections with configurable * minimum and maximum sizes. Connections are validated before * being handed out.

* *

Thread Safety

*

This class is thread-safe. All public methods use proper * synchronization.

* * @param The connection type to pool * * @author John Doe * @version 1.0.0 * @since 1.0.0 * * @see Connection * @see PoolConfig */ public class ConnectionPool implements AutoCloseable { /** * Creates a connection pool with the specified configuration. * * @param config the pool configuration * @throws IllegalArgumentException if config is null * @throws ConfigurationException if config values are invalid */ public ConnectionPool(PoolConfig config) { // Implementation } /** * Acquires a connection from the pool. * *

This method blocks until a connection becomes available * or the specified timeout expires.

* * @param timeout maximum time to wait for a connection * @return a valid connection from the pool * @throws TimeoutException if no connection available within timeout * @throws PoolClosedException if the pool has been closed */ public T acquire(Duration timeout) throws TimeoutException { // Implementation } /** * {@inheritDoc} * *

Closes all connections and releases resources.

*/ @Override public void close() { // Implementation } } ``` ### Method Documentation with Code Examples ```java /** * Executes a parameterized SQL query. * *

Parameters are bound in the order provided. Use {@code ?} * as placeholder in the query string.

* *

Example

* 
{@code
 * List users = db.query(
 *     "SELECT * FROM users WHERE age > ? AND status = ?",
 *     List.of(18, "active"),
 *     User.class
 * );
 * }
* * @param the result type * @param sql the SQL query with {@code ?} placeholders * @param params the parameter values (in order) * @param resultType the class to map results to * @return list of mapped results * @throws SQLException if query execution fails * @throws MappingException if result mapping fails * * @see #execute(String, List) for non-SELECT queries * @since 1.0.0 */ public List query(String sql, List params, Class resultType) throws SQLException { // Implementation } ``` ## Doxyfile Configuration ```ini # Doxyfile configuration # Project settings PROJECT_NAME = "MyLib" PROJECT_NUMBER = "1.0.0" PROJECT_BRIEF = "Database connectivity library" PROJECT_LOGO = logo.png # Input settings INPUT = src include FILE_PATTERNS = *.c *.cc *.cpp *.h *.hpp RECURSIVE = YES EXCLUDE = src/test src/vendor EXCLUDE_PATTERNS = *_test.cpp *_mock.h # Output settings OUTPUT_DIRECTORY = docs GENERATE_HTML = YES GENERATE_XML = YES GENERATE_LATEX = NO # HTML settings HTML_OUTPUT = html HTML_EXTRA_STYLESHEET = custom.css SEARCHENGINE = YES DISABLE_INDEX = NO GENERATE_TREEVIEW = YES # Graph settings HAVE_DOT = YES CALL_GRAPH = YES CALLER_GRAPH = YES CLASS_GRAPH = YES COLLABORATION_GRAPH = YES INCLUDE_GRAPH = YES INCLUDED_BY_GRAPH = YES DOT_IMAGE_FORMAT = svg # Documentation extraction EXTRACT_ALL = NO EXTRACT_PRIVATE = NO EXTRACT_STATIC = YES EXTRACT_LOCAL_CLASSES = YES # Warning settings WARN_IF_UNDOCUMENTED = YES WARN_IF_DOC_ERROR = YES WARN_NO_PARAMDOC = YES WARN_AS_ERROR = NO # Preprocessing ENABLE_PREPROCESSING = YES MACRO_EXPANSION = YES PREDEFINED = DOXYGEN_SKIP # Aliases for custom commands ALIASES = "thread_safe=\par Thread Safety\n" ALIASES += "performance=\par Performance\n" ``` ## Maven Javadoc Configuration ```xml org.apache.maven.plugins maven-javadoc-plugin 3.6.3 17 protected true all,-missing -Xdoclint:none https://docs.oracle.com/en/java/javase/17/docs/api/ apiNote a API Note: implSpec a Implementation Specification: implNote a Implementation Note: attach-javadocs jar ``` ## Workflow 1. **Detect project type** - Identify C/C++/Java project 2. **Locate sources** - Find source files and headers 3. **Generate config** - Create Doxyfile or configure Maven 4. **Parse comments** - Extract documentation from source 5. **Generate diagrams** - Create call graphs (if enabled) 6. **Build output** - Generate HTML/PDF/XML 7. **Analyze coverage** - Report documentation gaps ## Dependencies ### Doxygen ```bash # Ubuntu/Debian apt-get install doxygen graphviz # macOS brew install doxygen graphviz # Windows (chocolatey) choco install doxygen.install graphviz ``` ### Javadoc ```bash # Included with JDK java -version # JDK 11+ recommended ``` ## Best Practices Applied - Document all public API elements - Use @brief for one-line summaries - Include @param for all parameters - Specify @return values - Document exceptions with @throws - Add @code examples for complex functions - Use @see for cross-references - Enable warning for undocumented items ## References - Doxygen Manual: https://www.doxygen.nl/manual/ - Javadoc Guide: https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html - Doxygen Special Commands: https://www.doxygen.nl/manual/commands.html - Graphviz: https://graphviz.org/ ## Target Processes - api-doc-generation.js - sdk-doc-generation.js - arch-docs-c4.js - docs-audit.js