Bearsampp API Documentation

This repository contains the Doxygen configuration and generated documentation for the Bearsampp API. It provides an automated reference guide derived from the Bearsampp core source code, offering developers a comprehensive view of the platform’s capabilities, endpoints, and data structures.

What this repository contains

• doxygen/ — Doxygen configuration files and theme customizations
• html/ — Generated HTML documentation (ready to serve)
• README.md — This file

The documentation is generated from source code in the Bearsampp-development/sandbox/core directory.

Repository structure

api/
├── doxygen/                                  # Doxygen configuration and theme directory
│   ├── Doxyfile                              # [EDIT THIS] Main Doxygen configuration file
│   ├── Doxyfile.bak                          # Backup of previous configuration
│   ├── bin/                                  # [DO NOT EDIT] Doxygen executable binaries
│   │   ├── doxygen.exe                       # Doxygen command-line tool
│   │   ├── doxywizard.exe                    # Doxygen GUI configuration tool
│   │   └── libclang.dll                      # C/C++ parser library
│   ├── doxygen-custom/                       # [EDIT THIS] Custom theme overrides
│   │   ├── header.html                       # Custom HTML header template
│   │   ├── custom.css                        # Custom CSS styling
│   │   ├── custom-alternative.css            # Alternative theme CSS
│   │   └── toggle-alternative-theme.js       # Theme switcher JavaScript
│   ├── doxygen-awesome-css/                  # [REFERENCE ONLY] Awesome Doxygen theme (git submodule)
│   │   ├── doxygen-awesome.css               # Main awesome theme stylesheet
│   │   ├── doxygen-awesome-*.js              # Awesome theme feature scripts
│   │   ├── doxygen-custom/                   # Awesome theme example customizations
│   │   └── docs/                             # Awesome theme documentation
│   ├── examples/                             # [REFERENCE] Doxygen example files
│   │   ├── *.cpp, *.h, *.py                  # Example source code snippets
│   │   └── *.cfg                             # Example Doxygen configurations
│   ├── system/                               # [DO NOT EDIT] Doxygen installer files
│   │   └── unins000.*                        # Uninstaller (legacy)
│   ├── html/                                 # [GENERATED] Documentation output (old location)
│   └── doxygen_manual.chm                    # Doxygen documentation reference
├── html/                                      # [GENERATED] Pre-built documentation site
│   ├── index.html                            # Main documentation page
│   ├── search/                               # Search functionality files
│   ├── *.html                                # Generated documentation pages
│   └── ...                                   # (auto-generated by Doxygen)
├── .qodo/                                    # [INTERNAL] Qodo AI analysis data
├── README.md                                 # This file
└── .gitignore                                # Git ignore rules (if present)

Key points:

• [EDIT THIS] — Files you should modify to customize documentation
• [GENERATED] — Automatically created by Doxygen; don't commit these
• [DO NOT EDIT] — System/executable files or managed dependencies
• [REFERENCE ONLY] — Third-party or example files; shouldn't need modification

Using this repository

View the generated documentation

The html/ folder contains pre-built documentation. Open html/index.html in a web browser to browse the API reference:

• Classes/Types: Data structures and models used by the API
• Files: Source code files with inline documentation
• Search: Use the search feature to find specific endpoints, types, or concepts
• Dark Mode: Toggle is available in the top-right corner of the generated site

Rebuild the documentation locally

To regenerate documentation after source code changes:

1. Install Doxygen (if not already installed):

   • Windows: Download from https://www.doxygen.nl/download.html
   • macOS: brew install doxygen
   • Linux: apt-get install doxygen (Ubuntu/Debian)

2. Install Graphviz (optional, for diagrams):

   • Windows: https://graphviz.org/download/
   • macOS: brew install graphviz
   • Linux: apt-get install graphviz (Ubuntu/Debian)

3. Generate documentation from the api directory:

   doxygen doxygen/Doxyfile

4. View the output:

   • Documentation is generated to the location specified in Doxyfile (currently: E:/Bearsampp-development/sandbox/www/doxy)
   • Open the generated index.html in a web browser

Customize the documentation

Configure source paths and output:

• Edit doxygen/Doxyfile and update the INPUT and OUTPUT_DIRECTORY tags
• Common settings:
  • PROJECT_NAME: Documentation title
  • PROJECT_NUMBER: Version number (currently: 2026.7.11)
  • PROJECT_LOGO: Logo path (currently points to sandbox resources)
  • INPUT: Source code directory being documented
  • OUTPUT_DIRECTORY: Where generated docs are written

Customize appearance:

• doxygen/doxygen-custom/ — Place custom CSS/JavaScript overrides here
• doxygen/doxygen-awesome-*.js/.css — Theme files for the Awesome Doxygen theme
• Modify colors, fonts, or layout in these files

Add examples and guides:

• Place code examples in doxygen/examples/
• Reference them in source code using Doxygen commands (e.g., \example filename.cpp)

Key Doxygen features used

• Markdown support: Guides and documentation are written in Markdown
• Awesome theme: Clean, modern design with dark mode toggle
• Interactive TOC: Quick navigation through documentation sections
• Fragment copy button: Easy code snippet copying
• Tabs: Organize related content logically

Updating the documentation

When source code in Bearsampp-development/sandbox/core changes:

1. Code comments and documentation blocks in the source update automatically
2. Run doxygen doxygen/Doxyfile to regenerate HTML
3. Review changes in the generated html/ folder
4. Commit updated documentation to version control

Development workflow

For API developers:

• Write inline code documentation using Doxygen syntax
• Use /** ... */ blocks for classes, functions, and types
• Add \brief, \param, \return tags for clarity
• Preview changes locally before committing

For documentation maintainers:

• Verify Doxyfile points to correct source and output directories
• Test theme customizations in doxygen-custom/
• Ensure generated docs are readable and well-organized

Git workflow and what to commit

Files to commit:

• doxygen/Doxyfile — Configuration changes
• doxygen/doxygen-custom/*.css — Theme customizations
• doxygen/doxygen-custom/header.html — Custom header template
• doxygen/doxygen-custom/*.js — Custom JavaScript
• README.md — Documentation updates

Files to NOT commit:

• html/ — Generated documentation (add to .gitignore if not already)
• doxygen/html/ — Generated documentation
• doxygen/Doxyfile.bak — Backup files
• doxygen/bin/ — Executables and binaries
• doxygen/examples/ — Reference examples (usually not needed unless customizing)
• .qodo/ — Internal analysis data

Typical commit workflow:

1. Update source code documentation in Bearsampp-development/sandbox/core
2. Regenerate docs locally: doxygen doxygen/Doxyfile
3. Review changes in html/ folder
4. If changes look correct, commit only the Doxyfile or customization changes
5. Generated HTML should NOT be committed (handled by CI/CD)

Common tasks

Regenerate documentation after code changes

cd api
doxygen doxygen/Doxyfile

Update the project version number

Edit doxygen/Doxyfile and change the PROJECT_NUMBER tag:

PROJECT_NUMBER = 2024.6.0

Change the project logo

Edit doxygen/Doxyfile and update the PROJECT_LOGO path:

PROJECT_LOGO = /path/to/new/logo.png

Change theme colors

Edit doxygen/doxygen-custom/custom.css to override theme variables:

:root {
  --primary-color: #your-color;
  --text-color: #your-color;
}

Add custom header branding

Edit doxygen/doxygen-custom/header.html to add company branding, navigation links, or custom content

View Doxygen configuration options

Open doxygen/doxygen_manual.chm or visit https://doxygen.nl/manual/config.html

Troubleshooting

Documentation looks incomplete:

• Verify INPUT path in Doxyfile points to correct source directory
• Check that source code has Doxygen-compatible documentation comments (/** */)
• Ensure Doxygen version is compatible with Doxyfile settings

Styles not applying:

• Clear browser cache (Ctrl+Shift+Delete)
• Verify custom CSS file is in doxygen/doxygen-custom/
• Check that Doxyfile references custom files correctly
• Regenerate with doxygen doxygen/Doxyfile

Can't run Doxygen:

• Ensure doxygen/bin/doxygen.exe exists or Doxygen is in PATH
• Try installing latest Doxygen from https://www.doxygen.nl/download.html
• On Windows, may need Visual C++ redistributables

Git submodule issues with doxygen-awesome-css:

git submodule update --init --recursive

Support and issues

• If documentation appears incomplete or incorrect, verify that:
  • The Doxyfile INPUT path points to the correct source directory
  • Doxygen is version-compatible with the Doxyfile configuration
  • Source code includes proper documentation comments
• Check the git log for recent changes to Doxyfile or theme files
• For questions about the Awesome Doxygen theme, see: https://jothepro.github.io/doxygen-awesome-css/
• For Doxygen documentation syntax, see: https://doxygen.nl/manual/

License

See the LICENSE file in this repository for terms governing use of the documentation and code samples.