From: Vladimír Vondruš Date: Tue, 14 Aug 2018 19:12:51 +0000 (+0200) Subject: doxygen: support brief for enum values. X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~cjwatson/git?a=commitdiff_plain;h=1f8ecd338d351baf540c12a685c81c2e982e3121;p=blog.git doxygen: support brief for enum values. Turns out the enum values can be documented like this: //! A value enum Enum { Value, //!< A value }; and the /// or //! comments, unlike /** */, are treated as brief by doxygen. This is a completely valid use case and I don't want to force users to a different syntax here, so here ya go. --- diff --git a/doc/doxygen.rst b/doc/doxygen.rst index 6c9b1f05..3d0c8d0c 100644 --- a/doc/doxygen.rst +++ b/doc/doxygen.rst @@ -218,9 +218,6 @@ amount of generated content for no added value. this unnecessary, there's also search for this) - Verbatim listing of parsed headers, "Includes" and "Included By" lists are not present (use your IDE or GitHub instead) -- Brief description for enum values is ignored (only the detailed description - is used, as the brief description was never used anywhere else than next to - the detailed description) - Initializers of defines and variables are unconditionally ignored (one can always look in the sources, if really needed) - No section with list of examples or linking from function/class @@ -1426,6 +1423,7 @@ Property Description :py:`value.name` Value name [4]_ :py:`value.initializer` Value initializer. Can be empty. [1]_ :py:`value.is_deprecated` Whether the value is deprecated. [7]_ +:py:`value.brief` Brief description. Can be empty. [1]_ :py:`value.description` Detailed description. Can be empty. [2]_ =========================== =================================================== diff --git a/doxygen/dox2html5.py b/doxygen/dox2html5.py index 474ecf0a..8ab843dd 100755 --- a/doxygen/dox2html5.py +++ b/doxygen/dox2html5.py @@ -1479,10 +1479,9 @@ def parse_enum(state: State, element: ET.Element): value.name = enumvalue.find('name').text # There can be an implicit initializer for enum value value.initializer = html.escape(enumvalue.findtext('initializer', '')) - if ''.join(enumvalue.find('briefdescription').itertext()).strip(): - logging.warning("{}: ignoring brief description of enum value {}::{}".format(state.current, enum.name, value.name)) + value.brief = parse_desc(state, enumvalue.find('briefdescription')) value.description, value_search_keywords, value.is_deprecated = parse_enum_value_desc(state, enumvalue) - if value.description: + if value.brief or value.description: enum.has_value_details = True if enum.base_url == state.current_compound_url and not state.doxyfile['M_SEARCH_DISABLED']: result = Empty() diff --git a/doxygen/templates/details-enum.html b/doxygen/templates/details-enum.html index 40c8d677..504bee53 100644 --- a/doxygen/templates/details-enum.html +++ b/doxygen/templates/details-enum.html @@ -24,7 +24,12 @@ {{ value.name }} + {% if value.brief %}{# brief is not required for values #} +

{{ value.brief }}

+ {% endif %} + {% if value.description %}{# it can be only brief tho #} {{ value.description }} + {% endif %} {% endfor %} diff --git a/doxygen/test/compound_detailed/File.h b/doxygen/test/compound_detailed/File.h index 83df9f30..016ee61d 100644 --- a/doxygen/test/compound_detailed/File.h +++ b/doxygen/test/compound_detailed/File.h @@ -224,12 +224,6 @@ constexpr const int a = 25; /** @brief A namespace */ namespace Warning { -/** @brief Use the brief! */ -enum Enum { - /** @brief Don't use the brief! */ - Warn -}; - /** @brief Wrong @param wrong This parameter is not here diff --git a/doxygen/test/compound_detailed/namespaceWarning.html b/doxygen/test/compound_detailed/namespaceWarning.html index f3669d06..add2faef 100644 --- a/doxygen/test/compound_detailed/namespaceWarning.html +++ b/doxygen/test/compound_detailed/namespaceWarning.html @@ -27,21 +27,11 @@
  • Reference
    • -
    -

    Enums

    -
    -
    - enum Enum { Warn } -
    -
    Use the brief!
    -
    -

    Functions

    diff --git a/doxygen/test/contents_autobrief_cpp_comments/Doxyfile b/doxygen/test/contents_autobrief_cpp_comments/Doxyfile new file mode 100644 index 00000000..49e476ec --- /dev/null +++ b/doxygen/test/contents_autobrief_cpp_comments/Doxyfile @@ -0,0 +1,13 @@ +INPUT = File.h +QUIET = YES +GENERATE_HTML = NO +GENERATE_LATEX = NO +GENERATE_XML = YES +XML_PROGRAMLISTING = NO + +##! M_PAGE_FINE_PRINT = +##! M_THEME_COLOR = +##! M_FAVICON = +##! M_LINKS_NAVBAR1 = +##! M_LINKS_NAVBAR2 = +##! M_SEARCH_DISABLED = YES diff --git a/doxygen/test/contents_autobrief_cpp_comments/File.h b/doxygen/test/contents_autobrief_cpp_comments/File.h new file mode 100644 index 00000000..79670989 --- /dev/null +++ b/doxygen/test/contents_autobrief_cpp_comments/File.h @@ -0,0 +1,18 @@ +/// @file +/// A file + +/// A typedef +typedef int Typedef; + +//! An enum +enum Enum { + Value, //!< A brief description + Another, /**< A detailed description */ + + /** + * @brief A brief description + * + * And a detailed one as well. + */ + Last +}; diff --git a/doxygen/test/contents_autobrief_cpp_comments/File_8h.html b/doxygen/test/contents_autobrief_cpp_comments/File_8h.html new file mode 100644 index 00000000..8d10b013 --- /dev/null +++ b/doxygen/test/contents_autobrief_cpp_comments/File_8h.html @@ -0,0 +1,96 @@ + + + + + File.h file | My Project + + + + + +
    +
    +
    +
    +
    +

    + File.h file +

    +
    +

    Contents

    + +
    +

    A file

    +
    +

    Enums

    +
    +
    + enum Enum { Value, + Another, + Last } +
    +
    An enum.
    +
    +
    +
    +

    Typedefs

    +
    +
    + using Typedef = int +
    +
    A typedef.
    +
    +
    +
    +

    Enum documentation

    +
    +

    + enum Enum +

    +

    An enum.

    + + + + + + + + + + + + + + + + +
    Enumerators
    Value +

    A brief description.

    +
    Another +

    A detailed description

    +
    Last +

    A brief description.

    +

    And a detailed one as well.

    +
    +
    +
    +
    +
    +
    +
    + + diff --git a/doxygen/test/search/Dir/File.h b/doxygen/test/search/Dir/File.h index faea64df..adc95fdd 100644 --- a/doxygen/test/search/Dir/File.h +++ b/doxygen/test/search/Dir/File.h @@ -64,6 +64,9 @@ typedef int Typedef; @m_enum_values_as_keywords */ enum class Enum { + /** @brief Only a brief and no value */ + OnlyABrief, + /** * Enum value * diff --git a/doxygen/test/test_contents.py b/doxygen/test/test_contents.py index 8a25a66f..841a5793 100644 --- a/doxygen/test/test_contents.py +++ b/doxygen/test/test_contents.py @@ -258,6 +258,14 @@ class ParseError(BaseTestCase): # The index file should be generated, no abort self.assertTrue(os.path.exists(os.path.join(self.path, 'html', 'index.html'))) +class AutobriefCppComments(IntegrationTestCase): + def __init__(self, *args, **kwargs): + super().__init__(__file__, 'autobrief_cpp_comments', *args, **kwargs) + + def test(self): + self.run_dox2html5(wildcard='File_8h.xml') + self.assertEqual(*self.actual_expected_contents('File_8h.html')) + # JAVADOC_AUTOBRIEF should be nuked from orbit. Or implemented from scratch, # properly. diff --git a/doxygen/test/test_search.py b/doxygen/test/test_search.py index 05dfb2df..187f39ae 100755 --- a/doxygen/test/test_search.py +++ b/doxygen/test/test_search.py @@ -374,9 +374,9 @@ class Search(IntegrationTestCase): serialized = f.read() search_data_pretty = pretty_print(serialized)[0] #print(search_data_pretty) - self.assertEqual(len(serialized), 4572) + self.assertEqual(len(serialized), 4695) self.assertEqual(search_data_pretty, """ -52 symbols +53 symbols deprecated_macro [0] || | ($ || | ) [1] @@ -398,9 +398,9 @@ deprecated_macro [0] || | | foo [37] || | | | ($ || | | | ) [38] -|| | | class [52] -|| | | struct [53] -|| | | union [57] +|| | | class [53] +|| | | struct [54] +|| | | union [58] || | enum [34] || | | :$ || | | :deprecatedvalue [33] @@ -410,9 +410,9 @@ deprecated_macro [0] || value [33] || | riable [36] || typedef [35] -|| class [52] -|| struct [53] -|| union [57] +|| class [53] +|| struct [54] +|| union [58] |ir [24] || /$ || file.h [9] @@ -423,7 +423,7 @@ macro [3] || _with_params [7] || | ($ || | ) [8] -|in() [48] +|in() [49] glmacro() [4] | file() [10] | |oo() [13] @@ -432,48 +432,51 @@ glmacro() [4] | | () [26] | _dir [27] | |group [30] -| |enum [44] -| || _value [42] -| || _ext [41] -| |typedef [46] -| namespace() [50] -| struct() [55] -| union() [59] +| |enum [45] +| || _value [43] +| || _ext [42] +| |typedef [47] +| namespace() [51] +| struct() [56] +| union() [60] file.h [9] |oo [11, 14, 16, 18] || ($ || ) [12, 15, 17, 19] -namespace [49] +namespace [50] | :$ | :class [20] | | :$ | | :foo [11, 14, 16, 18] | | ($ | | ) [12, 15, 17, 19] -| enum [43] +| enum [44] | | :$ -| | :value [40] -| typedef [45] -| variable [47] -| struct [54] -| union [58] +| | :onlyabrief [40] +| | value [41] +| typedef [46] +| variable [48] +| struct [55] +| union [59] class [20] | :$ | :foo [11, 14, 16, 18] | ($ | ) [12, 15, 17, 19] a group [28, 29] -| page [51] -value [31, 40] -| riable [47] -enum [34, 43] +| page [52] +value [31, 41] +| riable [48] +enum [34, 44] | :$ | :deprecatedvalue [33] -| value [40] -typedef [45] -struct [54] -|ubpage [56] -union [58] +| onlyabrief [40] +| value [41] +onlyabrief [40] +typedef [46] +struct [55] +|ubpage [57] +union [59] 0: DEPRECATED_MACRO(a, b, c) [suffix_length=9, deprecated, type=DEFINE] -> DeprecatedFile_8h.html#a7f8376730349fef9ff7d103b0245a13e 1: [prefix=0[:56], suffix_length=7, deprecated, type=DEFINE] -> 2: /DeprecatedFile.h [prefix=23[:0], deprecated, type=FILE] -> DeprecatedFile_8h.html @@ -494,7 +497,7 @@ union [58] 17: [prefix=16[:62], suffix_length=3, deleted, type=FUNC] -> 18: ::foo(const Enum&, Typedef) [prefix=20[:28], suffix_length=22, type=FUNC] -> #aba8d57a830d4d79f86d58d92298677fa 19: [prefix=18[:62], suffix_length=20, type=FUNC] -> -20: ::Class [prefix=49[:0], type=CLASS] -> classNamespace_1_1Class.html +20: ::Class [prefix=50[:0], type=CLASS] -> classNamespace_1_1Class.html 21: glClass() [alias=20] -> 22: Deprecated List [type=PAGE] -> deprecated.html 23: DeprecatedDir [deprecated, type=DIR] -> dir_c6c97faf5a6cbd0f62c27843ce3af4d0.html @@ -514,26 +517,27 @@ union [58] 37: ::deprecatedFoo(int, bool, double) [prefix=39[:33], suffix_length=19, deprecated, type=FUNC] -> #a9a1b3fc71d294b548095985acc0d5092 38: [prefix=37[:67], suffix_length=17, deprecated, type=FUNC] -> 39: DeprecatedNamespace [deprecated, type=NAMESPACE] -> namespaceDeprecatedNamespace.html -40: ::Value [prefix=43[:57], type=ENUM_VALUE] -> a689202409e48743b914713f96d93947c -41: _EXT [alias=40, prefix=42[:0]] -> -42: _VALUE [alias=40, prefix=44[:0]] -> -43: ::Enum [prefix=49[:23], type=ENUM] -> #add172b93283b1ab7612c3ca6cc5dcfea -44: GL_ENUM [alias=43] -> -45: ::Typedef [prefix=49[:23], type=TYPEDEF] -> #abe2a245304bc2234927ef33175646e08 -46: GL_TYPEDEF [alias=45] -> -47: ::Variable [prefix=49[:23], type=VAR] -> #ad3121960d8665ab045ca1bfa1480a86d -48: GLSL: min() [alias=47, suffix_length=2] -> -49: Namespace [type=NAMESPACE] -> namespaceNamespace.html -50: glNamespace() [alias=49] -> -51: A page [type=PAGE] -> page.html -52: ::DeprecatedClass [prefix=39[:0], deprecated, type=STRUCT] -> structDeprecatedNamespace_1_1DeprecatedClass.html -53: ::DeprecatedStruct [prefix=39[:0], deprecated, type=STRUCT] -> structDeprecatedNamespace_1_1DeprecatedStruct.html -54: ::Struct [prefix=49[:0], type=STRUCT] -> structNamespace_1_1Struct.html -55: glStruct() [alias=54] -> -56: » Subpage [prefix=51[:0], type=PAGE] -> subpage.html -57: ::DeprecatedUnion [prefix=39[:0], deprecated, type=UNION] -> unionDeprecatedNamespace_1_1DeprecatedUnion.html -58: ::Union [prefix=49[:0], type=UNION] -> unionNamespace_1_1Union.html -59: glUnion() [alias=58] -> +40: ::OnlyABrief [prefix=44[:57], type=ENUM_VALUE] -> a9b0246417d89d650ed429f1b784805eb +41: ::Value [prefix=44[:57], type=ENUM_VALUE] -> a689202409e48743b914713f96d93947c +42: _EXT [alias=41, prefix=43[:0]] -> +43: _VALUE [alias=41, prefix=45[:0]] -> +44: ::Enum [prefix=50[:23], type=ENUM] -> #add172b93283b1ab7612c3ca6cc5dcfea +45: GL_ENUM [alias=44] -> +46: ::Typedef [prefix=50[:23], type=TYPEDEF] -> #abe2a245304bc2234927ef33175646e08 +47: GL_TYPEDEF [alias=46] -> +48: ::Variable [prefix=50[:23], type=VAR] -> #ad3121960d8665ab045ca1bfa1480a86d +49: GLSL: min() [alias=48, suffix_length=2] -> +50: Namespace [type=NAMESPACE] -> namespaceNamespace.html +51: glNamespace() [alias=50] -> +52: A page [type=PAGE] -> page.html +53: ::DeprecatedClass [prefix=39[:0], deprecated, type=STRUCT] -> structDeprecatedNamespace_1_1DeprecatedClass.html +54: ::DeprecatedStruct [prefix=39[:0], deprecated, type=STRUCT] -> structDeprecatedNamespace_1_1DeprecatedStruct.html +55: ::Struct [prefix=50[:0], type=STRUCT] -> structNamespace_1_1Struct.html +56: glStruct() [alias=55] -> +57: » Subpage [prefix=52[:0], type=PAGE] -> subpage.html +58: ::DeprecatedUnion [prefix=39[:0], deprecated, type=UNION] -> unionDeprecatedNamespace_1_1DeprecatedUnion.html +59: ::Union [prefix=50[:0], type=UNION] -> unionNamespace_1_1Union.html +60: glUnion() [alias=59] -> """.strip()) class SearchLongSuffixLength(IntegrationTestCase):