From 98f7779b38ddbce9eaff8ccf907391fea4d1488c Mon Sep 17 00:00:00 2001 From: =?utf8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Sun, 7 Jun 2020 13:18:39 +0200 Subject: [PATCH] doc: clarify some more Doxygen (mis)behavior. --- doc/documentation/doxygen.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/doc/documentation/doxygen.rst b/doc/documentation/doxygen.rst index 78f13ea7..411fcfac 100644 --- a/doc/documentation/doxygen.rst +++ b/doc/documentation/doxygen.rst @@ -245,6 +245,10 @@ amount of generated content for no added value. - Proper scoping for friend and related functions/classes/variables etc. Doxygen doesn't provide any namespace scoping for these and at the moment I have no way to deduct that information. +- APIs listed in file documentation pages lose all namespace information (and + when it appears in search, it's prefixed with the file name instead of the + namespace). This is due to several bugs on Doxygen side, which still need + to be patched (or worked around). `Configuration`_ ================ @@ -591,6 +595,13 @@ potential "fix" to this is enabling the :ini:`EXTRACT_ALL` option, but that exposes all symbols, including private and file-local ones --- which, most probably, is *not* what you want. +If you have namespaces not documented, Doxygen will by put function docs into +file pages --- but it doesn't put them into the XML output, meaning all links +to them will lead nowhere and the functions won't appear in search either. +To fix this, enable the :ini:`XML_NS_MEMB_FILE_SCOPE` option as described in +the `Namespace members in file scope`_ section below; if you document all +namespaces this problem will go away as well. + `Content`_ ========== @@ -705,6 +716,11 @@ its XML output. To match the behavior of stock HTML output, enable the In order to use the :ini:`XML_NS_MEMB_FILE_SCOPE` option, you need Doxygen 1.8.15 (released December 2018). +Please note that APIs listed in file documentation pages lose all namespace +information (and when it appears in search, it's prefixed with the file name +instead of the namespace). This is due to several bugs on Doxygen side, which +still need to be patched (or worked around). + `Private virtual functions`_ ---------------------------- -- 2.30.2