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 6c9b1f0583016797aebf9767e52a846f7ccf0ffe..3d0c8d0cc4977b63c8ed608c1d9e59a7570aca01 100644 (file)
--- 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 474ecf0afb950ca4176baddb64b25ec8efaed567..8ab843dd644b40ad3a613744f18b61a369006880 100755 (executable)
--- 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 40c8d6777414cba3e9d500f7de5f9c9c71af63cb..504bee5335b9e9687fdc9ae4e9706b033fee708e 100644 (file)
--- a/doxygen/templates/details-enum.html
+++ b/doxygen/templates/details-enum.html
@@ -24,7 +24,12 @@
                 <tr>
                   <td><a href="#{{ value.id }}" class="m-dox-self" name="{{ value.id }}">{{ value.name }}</a></td>
                   <td>
+                  {% if value.brief %}{# brief is not required for values #}
+                  <p>{{ value.brief }}</p>
+                  {% endif %}
+                  {% if value.description %}{# it can be only brief tho #}
 {{ value.description }}
+                  {% endif %}
                   </td>
                 </tr>
                 {% endfor %}

diff --git a/doxygen/test/compound_detailed/File.h b/doxygen/test/compound_detailed/File.h
index 83df9f306d8778c299521045a4dcb2e5248c0ba3..016ee61d73530bb3eb5c99aacdf7a6a57864c37d 100644 (file)
--- 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 f3669d06fd9505052b0ef513acd1557dc5c8ef02..add2faef29c747ec6069474636b2c35dd934c482 100644 (file)
--- a/doxygen/test/compound_detailed/namespaceWarning.html
+++ b/doxygen/test/compound_detailed/namespaceWarning.html
@@ -27,21 +27,11 @@
             <li>
               Reference
               <ul>
-                <li><a href="#enum-members">Enums</a></li>
                 <li><a href="#func-members">Functions</a></li>
               </ul>
             </li>
           </ul>
         </div>
-        <section id="enum-members">
-          <h2><a href="#enum-members">Enums</a></h2>
-          <dl class="m-dox">
-            <dt>
-              <span class="m-dox-wrap-bumper">enum <a href="#a6e48c63bc575702198dfcc3501fc8bb8" class="m-dox-self" name="a6e48c63bc575702198dfcc3501fc8bb8">Enum</a> { </span><span class="m-dox-wrap"><a href="#a6e48c63bc575702198dfcc3501fc8bb8a63997f6aebd31d3b13d6bbb51c87c4f0" class="m-dox">Warn</a> }</span>
-            </dt>
-            <dd>Use the brief!</dd>
-          </dl>
-        </section>
         <section id="func-members">
           <h2><a href="#func-members">Functions</a></h2>
           <dl class="m-dox">

diff --git a/doxygen/test/contents_autobrief_cpp_comments/Doxyfile b/doxygen/test/contents_autobrief_cpp_comments/Doxyfile
new file mode 100644 (file)
index 0000000..49e476e
--- /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 (file)
index 0000000..7967098
--- /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 (file)
index 0000000..8d10b01
--- /dev/null
+++ b/doxygen/test/contents_autobrief_cpp_comments/File_8h.html
@@ -0,0 +1,96 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <title>File.h file | My Project</title>
+  <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Source+Sans+Pro:400,400i,600,600i%7CSource+Code+Pro:400,400i,600" />
+  <link rel="stylesheet" href="m-dark+doxygen.compiled.css" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+</head>
+<body>
+<header><nav id="navigation">
+  <div class="m-container">
+    <div class="m-row">
+      <a href="index.html" id="m-navbar-brand" class="m-col-t-8 m-col-m-none m-left-m">My Project</a>
+    </div>
+  </div>
+</nav></header>
+<main><article>
+  <div class="m-container m-container-inflatable">
+    <div class="m-row">
+      <div class="m-col-l-10 m-push-l-1">
+        <h1>
+          File.h <span class="m-thin">file</span>
+        </h1>
+        <div class="m-block m-default">
+          <h3>Contents</h3>
+          <ul>
+            <li>
+              Reference
+              <ul>
+                <li><a href="#enum-members">Enums</a></li>
+                <li><a href="#typedef-members">Typedefs</a></li>
+              </ul>
+            </li>
+          </ul>
+        </div>
+<p>A file</p>
+        <section id="enum-members">
+          <h2><a href="#enum-members">Enums</a></h2>
+          <dl class="m-dox">
+            <dt>
+              <span class="m-dox-wrap-bumper">enum <a href="#a8150b7776c2a1749101acf22e868d091" class="m-dox">Enum</a> { </span><span class="m-dox-wrap"><a href="#a8150b7776c2a1749101acf22e868d091a050889cfb2c606473596b8f70f702769" class="m-dox">Value</a>,
+              <a href="#a8150b7776c2a1749101acf22e868d091a53303616791b3f53611d88fb24bda2d9" class="m-dox">Another</a>,
+              <a href="#a8150b7776c2a1749101acf22e868d091ac2a3856002491cf465725e8d1108f796" class="m-dox">Last</a> }</span>
+            </dt>
+            <dd>An enum.</dd>
+          </dl>
+        </section>
+        <section id="typedef-members">
+          <h2><a href="#typedef-members">Typedefs</a></h2>
+          <dl class="m-dox">
+            <dt>
+              using <a href="#aedec7b8d93c84ed3293e685c1e0b444e" class="m-dox-self" name="aedec7b8d93c84ed3293e685c1e0b444e">Typedef</a> = int
+            </dt>
+            <dd>A typedef.</dd>
+          </dl>
+        </section>
+        <section>
+          <h2>Enum documentation</h2>
+          <section class="m-dox-details" id="a8150b7776c2a1749101acf22e868d091"><div>
+            <h3>
+              enum <a href="#a8150b7776c2a1749101acf22e868d091" class="m-dox-self">Enum</a>
+            </h3>
+            <p>An enum.</p>
+            <table class="m-table m-fullwidth m-flat m-dox">
+              <thead><tr><th style="width: 1%">Enumerators</th><th></th></tr></thead>
+              <tbody>
+                <tr>
+                  <td><a href="#a8150b7776c2a1749101acf22e868d091a050889cfb2c606473596b8f70f702769" class="m-dox-self" name="a8150b7776c2a1749101acf22e868d091a050889cfb2c606473596b8f70f702769">Value</a></td>
+                  <td>
+                  <p>A brief description.</p>
+                  </td>
+                </tr>
+                <tr>
+                  <td><a href="#a8150b7776c2a1749101acf22e868d091a53303616791b3f53611d88fb24bda2d9" class="m-dox-self" name="a8150b7776c2a1749101acf22e868d091a53303616791b3f53611d88fb24bda2d9">Another</a></td>
+                  <td>
+<p>A detailed description</p>
+                  </td>
+                </tr>
+                <tr>
+                  <td><a href="#a8150b7776c2a1749101acf22e868d091ac2a3856002491cf465725e8d1108f796" class="m-dox-self" name="a8150b7776c2a1749101acf22e868d091ac2a3856002491cf465725e8d1108f796">Last</a></td>
+                  <td>
+                  <p>A brief description.</p>
+<p>And a detailed one as well.</p>
+                  </td>
+                </tr>
+              </tbody>
+            </table>
+          </div></section>
+        </section>
+      </div>
+    </div>
+  </div>
+</article></main>
+</body>
+</html>

diff --git a/doxygen/test/search/Dir/File.h b/doxygen/test/search/Dir/File.h
index faea64dfdc1017e9fa78b645b50f1fd3949e80ab..adc95fdde045963725979ab6c22cb55b1460194d 100644 (file)
--- 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 8a25a66f71ef11ab9380b5c1b2a01fa6f99bcac0..841a5793946bade70865843089130012946a0b9e 100644 (file)
--- 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 05dfb2df87d57e39e1cb2344b24fe4c98284fd51..187f39ae9ba9d1e08f7960d29a2e460078c068b4 100755 (executable)
--- 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):