From: Vladimír Vondruš Date: Sat, 10 Feb 2018 15:06:42 +0000 (+0100) Subject: doxygen: be compatible with stock HTML output for undocumented symbols. X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~cjwatson/git?a=commitdiff_plain;h=2f5b2f5d670d2ff0e1ace34c49a52016a8d4eff5;p=blog.git doxygen: be compatible with stock HTML output for undocumented symbols. In particular, if given compound has neither brief nor detailed docs, produce output for it only if it's a page or a group (because those need to be explicitly created). Before only file/dir docs behaved like this, not namespaces or classes. --- diff --git a/doxygen/dox2html5.py b/doxygen/dox2html5.py index 609df177..882c94f7 100755 --- a/doxygen/dox2html5.py +++ b/doxygen/dox2html5.py @@ -1633,9 +1633,9 @@ def extract_metadata(state: State, xml): # Compound URL is ID, except for index page compound.url = (compounddef.find('compoundname').text if compound.kind == 'page' else compound.id) + '.html' compound.brief = parse_desc(state, compounddef.find('briefdescription')) - # Groups are explicitly created so they *have details*, other things need - # to have at least some documentation - compound.has_details = compound.kind == 'group' or compound.brief or compounddef.find('detaileddescription') + # Groups and pages are explicitly created so they *have details*, other + # things need to have at least some documentation + compound.has_details = compound.kind in ['group', 'page'] or compound.brief or compounddef.find('detaileddescription') compound.children = [] compound.parent = None # is filled in by postprocess_state() @@ -1856,9 +1856,10 @@ def parse_xml(state: State, xml: str): logging.debug("{}: only private things, skipping".format(state.current)) return None - # Ignoring dirs/files w/o any description - if compounddef.attrib['kind'] in ['dir', 'file'] and not compounddef.find('briefdescription') and not compounddef.find('detaileddescription'): - logging.debug("{}: file/dir documentation empty, skipping".format(state.current)) + # Ignoring compounds w/o any description, except for pages and groups, + # which are created explicitly + if not compounddef.find('briefdescription') and not compounddef.find('detaileddescription') and not compounddef.attrib['kind'] in ['page', 'group']: + logging.debug("{}: neither brief nor detailed description present, skipping".format(state.current)) return None compound = Empty() diff --git a/doxygen/test/compound_detailed/File.h b/doxygen/test/compound_detailed/File.h index 3d6329c6..401cd8d2 100644 --- a/doxygen/test/compound_detailed/File.h +++ b/doxygen/test/compound_detailed/File.h @@ -91,6 +91,7 @@ And we have some detailed docs as well. */ namespace Namee {} +/** @brief A namespace */ namespace Foo { /** @@ -161,6 +162,7 @@ void thisIsAShittyWayToPassAVectorButWhatever(float x, float y, float z); } +/** @brief A namespace */ namespace Eno { /** @brief Boolean */ @@ -177,6 +179,7 @@ enum { } +/** @brief A namespace */ namespace Type { /** @@ -195,6 +198,7 @@ typedef void(*Func)(int, std::string&); } +/** @brief A namespace */ namespace Var { /** @@ -206,6 +210,7 @@ constexpr const int a = 25; } +/** @brief A namespace */ namespace Warning { /** @brief Use the brief! */ diff --git a/doxygen/test/compound_detailed/File_8h.html b/doxygen/test/compound_detailed/File_8h.html index 45098284..3928cd18 100644 --- a/doxygen/test/compound_detailed/File_8h.html +++ b/doxygen/test/compound_detailed/File_8h.html @@ -41,6 +41,16 @@
namespace Namee
Namespace docs.
+
namespace Foo
+
A namespace.
+
namespace Eno
+
A namespace.
+
namespace Type
+
A namespace.
+
namespace Var
+
A namespace.
+
namespace Warning
+
A namespace.
diff --git a/doxygen/test/compound_detailed/namespaceEno.html b/doxygen/test/compound_detailed/namespaceEno.html index 981ed8ea..28ac5775 100644 --- a/doxygen/test/compound_detailed/namespaceEno.html +++ b/doxygen/test/compound_detailed/namespaceEno.html @@ -20,6 +20,7 @@

Eno namespace

+

A namespace.

Enums

diff --git a/doxygen/test/compound_detailed/namespaceFoo.html b/doxygen/test/compound_detailed/namespaceFoo.html index 918fdfc2..ec53c234 100644 --- a/doxygen/test/compound_detailed/namespaceFoo.html +++ b/doxygen/test/compound_detailed/namespaceFoo.html @@ -20,6 +20,7 @@

Foo namespace

+

A namespace.

Contents

    diff --git a/doxygen/test/compound_detailed/namespaceType.html b/doxygen/test/compound_detailed/namespaceType.html index 458db06c..e5ac4c26 100644 --- a/doxygen/test/compound_detailed/namespaceType.html +++ b/doxygen/test/compound_detailed/namespaceType.html @@ -20,6 +20,7 @@

    Type namespace

    +

    A namespace.

    Contents

      diff --git a/doxygen/test/compound_detailed/namespaceVar.html b/doxygen/test/compound_detailed/namespaceVar.html index 1a838d9e..4d841c40 100644 --- a/doxygen/test/compound_detailed/namespaceVar.html +++ b/doxygen/test/compound_detailed/namespaceVar.html @@ -20,6 +20,7 @@

      Var namespace

      +

      A namespace.

      Contents

        diff --git a/doxygen/test/compound_detailed/namespaceWarning.html b/doxygen/test/compound_detailed/namespaceWarning.html index 5252e48b..dec9a10a 100644 --- a/doxygen/test/compound_detailed/namespaceWarning.html +++ b/doxygen/test/compound_detailed/namespaceWarning.html @@ -20,6 +20,7 @@

        Warning namespace

        +

        A namespace.

        Contents