# Doxygen

The [Breathe](https://breathe.readthedocs.io/) extension integrates Doxygen-generated documentation into Sphinx.

## Supported languages

Breathe supports any language that Doxygen can parse:

* C
* C++
* C#
* Objective-C
* PHP
* Java
* Python (limited)
* Fortran
* VHDL

## Setup

Install Breathe:

```bash
pip install breathe
```

Configure Doxygen to generate XML output in your `Doxyfile`:

```text
GENERATE_XML = YES
XML_OUTPUT = xml
```

Add Breathe to your `conf.py`:

```python
extensions = ['breathe']

breathe_projects = {
    'myproject': './doxygen/xml/'
}
breathe_default_project = 'myproject'
```

## Basic usage

### Document a class

```rst
.. doxygenclass:: DatabaseConnection
   :members:
```

### class DatabaseConnection

Manages database connections. 

This class provides methods for connecting to, querying, and disconnecting from a database. 

### Public Functions

### DatabaseConnection(const std::string &host, int port = 9042, const std::string &username = "")

Construct a new Database Connection object. 

* **Parameters:**
  * **host** – The database host address 
  * **port** – The database port number (default: 9042) 
  * **username** – Optional username for authentication 

### bool connect()

Establish a connection to the database. 

* **Throws:**
   – if connection fails after retries 
* **Returns:**
  true if connection was successful 
* **Returns:**
  false if connection failed 

### std::string execute(const std::string &query)

Execute a query on the database. 

* **Parameters:**
  **query** – The SQL query string to execute 
* **Throws:**
   – if not connected to database 
* **Returns:**
  Query results as a string 

### void disconnect()

Close the database connection. 

### Document a function

```rst
.. doxygenfunction:: format_query
```

### std::string format_query(const std::string &query, int indent = 4)

Format a SQL query string. 

* **Parameters:**
  * **query** – The SQL query template 
  * **indent** – Number of spaces for indentation (default: 4) 
* **Returns:**
  Formatted SQL query string 

## Common options

### Select specific members

```rst
.. doxygenclass:: DatabaseConnection
   :members: connect, disconnect
```

### Include private members

```rst
.. doxygenclass:: DatabaseConnection
   :members:
   :private-members:
```

### Include undocumented members

```rst
.. doxygenclass:: DatabaseConnection
   :members:
   :undoc-members:
```

## Doxygen comment syntax

### C++ example

```cpp
/**
 * @brief Establishes a connection
 * @param host The database host address
 * @param port The database port number
 * @return true if connection successful
 * @throw ConnectionError if connection fails
 */
bool connect(const std::string& host, int port);
```

### C example

```c
/**
 * @brief Connect to database
 * @param[in] config Connection configuration
 * @return Connection handle or NULL on failure
 */
connection_t* db_connect(const connection_config_t* config);
```

## Configuration

Common settings in `conf.py`:

```python
breathe_default_members = ('members', 'undoc-members')
breathe_show_define_initializer = True
```

## Automatic API generation

For large projects, use [Exhale](https://exhale.readthedocs.io/) to automatically generate API documentation pages:

```bash
pip install exhale
```

Configure in `conf.py`:

```python
extensions = ['breathe', 'exhale']

exhale_args = {
    'containmentFolder': './api',
    'rootFileName': 'library_root.rst',
    'rootFileTitle': 'API Reference',
    'doxygenStripFromPath': '..',
}
```

Exhale will automatically create a page for each class, function, and file in your project.