|
Doxygen XLinks
|
by |  |
|
|
Doxygen XLinks
|
by | |
|
DoxygenXLinks is a post-processor for Doxygen 
, the de-facto standard tool for C++ source-code documentation. It enhances the generated HTML output in two fundamental ways:
The first feature is fully independent of the second: even if you keep using Doxygen's \ref-commands, running DoxygenXLinks as a plain post-processor makes all your links shine according to your stylesheet.
Doxygen's \ref-command is powerful, but for large, long-lived projects it becomes verbose and error-prone. A single reference such as
\ref alib::expressions::detail::VirtualMachine "VirtualMachine"
has to spell out the full scope and repeat the display text by hand. When an entity is renamed during refactoring, every hand-written display text silently goes stale and the documentation becomes wrong - without anyone noticing.
The ALib C++ Framework, for which DoxygenXLinks was originally created, places more than 11,000 cross-references by hand. DoxygenXLinks was built to make this effort as effortless and as safe as possible:
DoxygenXLinks is particularly suited for:
This is the first release of DoxygenXLinks (version 2606R0), building on ALib V2605R1.
All details of changes are documented in the General Library Manual.
Suppose you want to link to the class alib::expressions::detail::VirtualMachine. With plain Doxygen you would write:
\ref alib::expressions::detail::VirtualMachine "VirtualMachine"
Written as an XLink, the very same reference is simply:
#"VirtualMachine"
From 63 characters, only 17 remain - and the generated HTML output is 100% identical. DoxygenXLinks searches the indexed tag-files, finds the unique target, and derives the display text ("VirtualMachine") from the entity name.
When a reference is not unique, DoxygenXLinks does not guess. Instead it reports the ambiguity with all candidates and the exact source location, for example:
Ambiguous XLink #"Exceptions".
Could be (E) enumeration alib::variables::Exceptions -> .../namespacealib_1_1variables.html
Could be (E) enumeration alib::expressions::Exceptions -> .../namespacealib_1_1expressions.html
Could be (E) enumeration alib::app::App::Exceptions -> .../classalib_1_1app_1_1App.html
Could be (E) enumeration dxl::Exceptions -> .../namespacedxl.html
@ docs/dxl_manual.dox.md:404:5
Disambiguating is then a matter of adding a short, lazy "scope-hint" - a case-insensitive substring of the path - e.g. Exceptions.
This small example already demonstrates several core DoxygenXLinks capabilities:
DoxygenXLinks will not slow down your build. Being built on the ALib C++ Framework, it reaches high throughput: on the ALib documentation it replaced 87,239 anchors across 2,123 HTML-files in just 83 milliseconds. Processing DoxygenXLinks's own documentation (~7,600 links, including indexing the ~8,700-entity ALib tag-file) takes about 15 milliseconds. As a post-processor, DoxygenXLinks works on data that Doxygen has just read and written, so disk I/O is effectively free.
DoxygenXLinks has been written and tested with Doxygen versions 1.14, 1.15, 1.16, and 1.16.1.
The current release was tested on the following platform combinations:
See chapter 6. Building DoxygenXLinks for details of how to compile and use DoxygenXLinks in your environment, and chapter 5. Usage (Calling The Tool) for how to integrate it into your build process.
DoxygenXLinks is free software, can be downloaded at Github and sources are published under MIT Software License:
MIT License Copyright (c) 2013-2026 A-Worx GmbH, Germany Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
DoxygenXLinks is built on the ALib C++ Framework, which provides its strings, boxing, expression engine, memory management, and diagnostics. ALib has no mandatory third-party dependencies.
At runtime, DoxygenXLinks operates on the output of Doxygen (version 1.14 or newer) and reads Doxygen's tag-files and Doxyfile.
We are happy about community input and contributions.
This first version supports the C++ language only. However, because Doxygen uses a consistent XML structure for its tag-files across all of its supported languages (Java, Python, C#, ...), adopting DoxygenXLinks for other languages should be quite straightforward - the core logic of "global search" and "scope-hints" remains the same. The community is warmly invited to contribute support for further languages on GitHub .
Our thanks go to all supporters that did and do help realizing this project. Furthermore, to just all of these millions of supporters of free software, including:
, without which this tool would have no reason to exist. project and community, project, project, for providing the best in class IDE CLion .