From 5017f95dba0ba988008b96a757fd1e49c1aa6376 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Tue, 1 Jan 2019 00:52:05 +0100 Subject: [PATCH] doxygen: more detailed docs explaining the #include behavior. And required patches. --- doc/doxygen.rst | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/doc/doxygen.rst b/doc/doxygen.rst index b9203321..e218d436 100644 --- a/doc/doxygen.rst +++ b/doc/doxygen.rst @@ -656,6 +656,37 @@ 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). +`Include files`_ +---------------- + +Doxygen by default shows corresponding :cpp:`#include`\ s only for classes. The +m.css Doxygen theme shows it also for namespaces, free functions, enums, +typedefs, variables and :cpp:`#define`\ s. The rules are: + +- For classes, :cpp:`#include` information is always shown on the top +- If a namespace doesn't contain any inner namespaces or classes and consists + only of functions (enums, typedefs, variables) that are all declared in the + same header file, the :cpp:`#include` information is shown only globally at + the top, similarly to classes +- If a namespace contains inner classes/namespaces, or is spread over multiple + headers, the :cpp:`#include` information is shown locally for each member +- Files don't show any include information, as it is known implicitly +- In case of modules (grouped using ``@defgroup``), the :cpp:`#include` info + is always shown locally for each member. This includes also :cpp:`#define`\ s. + +This feature is enabled by default, disable :ini:`SHOW_INCLUDE_FILES` to hide +all :cpp:`#include`-related information: + +.. code:: ini + + SHOW_INCLUDE_FILES = NO + +.. note-warning:: Doxygen patches + + Current stable Doxygen release (1.8.15) doesn't correctly provide location + information for function and variable declarations. A fix is submitted in + :gh:`doxygen/doxygen#6722`, which is not integrated yet. + `Code highlighting`_ -------------------- -- 2.30.2