omnidocs / doxygen
Omnidocs Doxygen: a C or C++ project's reference from Doxygen's XML output - its main page, a page per namespace, class, struct and file with its public members, their declarations, parameters and returns; notes, warnings and code examples in omnidocs' conventions.
Requires
- php: >=8.2
- ext-dom: *
- ext-libxml: *
- omnisense/omnidocs: ^1.0
Requires (Dev)
- omnisense/contracts: ^1.0
- phpunit/phpunit: ^11.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
A C or C++ project's reference from Doxygen's XML output (GENERATE_XML=YES), as an
omnidocs manual: its main page as the home, then a page
per namespace, class, struct, union and file - its description, its bases, its public members with
their declaration, text, parameters and return, enum values - at the anchors Doxygen gives them; every
compound and public member an API entry. \note, \warning, \see, \since, \deprecated are callouts, a
code example a frame, a \ref a link to its page and anchor, a declaration's file and line a link to
the repository.
Installation and a first use
composer require omnidocs/doxygen
It reads the XML Doxygen writes (GENERATE_XML=YES in the Doxyfile, then doxygen). Doxygen is the
documented project's tool, not a dependency: the package needs PHP 8.2 with ext-dom, no network, no
account. To try it without Doxygen, read the TinyXML-2 output its tests use, installed with it:
require __DIR__.'/vendor/autoload.php'; use Omnidocs\Model\Version; use Omnidocs\Doxygen\DoxygenSourceFactory; $source = (new DoxygenSourceFactory())->create(['dir' => __DIR__.'/vendor/omnidocs/doxygen/Tests/Fixtures/tinyxml2']); $version = new Version('10.0', $source); foreach ($version->pages() as $node) { echo $node->title, "\n"; } echo count($version->symbols()), " API entries\n";
Its tests (composer install then vendor/bin/phpunit in a checkout, or every package at once in
omnidocs' Docker harness)
read that committed output: Doxygen is not needed to run them. The harness's doxygen service
regenerates the whole of it with Doxygen 1.11.0.
With a project's own output:
$reference = (new Omnidocs\Doxygen\DoxygenSourceFactory())->create(['dir' => 'build/xml']);
| Option | Default | Meaning |
|---|---|---|
dir |
(required) | Doxygen's XML output |
source |
"" |
what Doxygen's file paths are relative to, in the repository |
title |
Reference |
the home's title when the project has no main page |
labels |
English | the callouts' words |
Verified, and not
- Verified (omnidocs' harness, PHP 8.4): omnidocs' conformance suite on TinyXML-2 (leethomason/tinyxml2
10.0.0) through Doxygen 1.11.0 with its own configuration - its whole XML output as the fixture: the
main page, 24 compounds, 407 entries;
BareTest. - Not verified: Doxygen's groups (\defgroup) and related pages beyond the main page; C#, Java and Python projects; diagrams (Doxygen draws them as images, not in the XML).
Licence: MIT.