documentation/doxygen: don't omit functions w/o brief from file docs.

Before, functions that contained for example /** \overload */ were
omitted from file docs, leading to user confusion.

And document the behavior more thoroughly -- took me a while to realize
this condition was really responsible for this.

diff --git a/documentation/doxygen.py b/documentation/doxygen.py
index 3d34a01e1b2974bfbe1b18cd6c68a785529d9b1b..2be78596882059a5e3636738129218eb5dd54ec9 100755 (executable)
--- a/documentation/doxygen.py
+++ b/documentation/doxygen.py
@@ -2121,11 +2121,31 @@ def parse_func(state: State, element: ET.Element):
     # Some param description got unused
     if params: logging.warning("{}: function parameter description doesn't match parameter names: {}".format(state.current, repr(params)))
 
-    if func.base_url == state.current_compound_url and (func.description or func.has_template_details or func.has_param_details or func.return_value or func.return_values or func.exceptions):
-        func.has_details = True # has_details might already be True from above
-    if func.brief or func.has_details:
-        # Avoid duplicates in search
-        if func.base_url == state.current_compound_url and not state.config['SEARCH_DISABLED']:
+    # If there's a detailed description or template, param, return value or
+    # exception details, the function can have a detailed block
+    #
+    # This also means has_details is always False for functions in
+    # namespaces referenced from header file docs.
+    can_have_details = func.description or func.has_template_details or func.has_param_details or func.return_value or func.return_values or func.exceptions
+
+    # If we're in the compound where the function originates (so in the
+    # namespace where the function is and not in a header file docs which
+    # reference functions from that namespace)
+    if func.base_url == state.current_compound_url:
+        # This means has_details is always False for namespace functions
+        # referenced from header file docs -- if it wouldn't be, the same docs
+        # would be shown both in the namespace and in file docs, which is a
+        # useless duplication.
+        #
+        # The has_details might also already be True from above when we need to
+        # show a different include than the global compound include.
+        if can_have_details:
+            func.has_details = True
+
+        # Then, if the function has some actual documentation, add it to the
+        # search. Again, the compound URL check means the search entry is not
+        # duplicated for functions referenced from file docs.
+        if (func.brief or func.has_details) and not state.config['SEARCH_DISABLED']:
             result = Empty()
             result.flags = ResultFlag.from_type((ResultFlag.DEPRECATED if func.deprecated else ResultFlag(0))|(ResultFlag.DELETED if func.is_deleted else ResultFlag(0)), EntryType.FUNC)
             result.url = func.base_url + '#' + func.id
@@ -2135,8 +2155,11 @@ def parse_func(state: State, element: ET.Element):
             result.params = [param.type for param in func.params]
             result.suffix = func.suffix
             state.search += [result]
-        return func
-    return None
+
+    # Return the function only if it has some documentation. Testing just for
+    # func.has_details would errorneously omit functions that have e.g. just
+    # /** @overload */ from file docs.
+    return func if func.brief or can_have_details else None
 
 def parse_var(state: State, element: ET.Element):
     assert element.tag == 'memberdef' and element.attrib['kind'] == 'variable'

diff --git a/documentation/test_doxygen/compound_namespace_members_in_file_scope/File.h b/documentation/test_doxygen/compound_namespace_members_in_file_scope/File.h
index 94fcbec8595902a688037ba4f42598de6acecc99..1aa5cd008f04720ab3f5aa59b11447d1a2b28fb5 100644 (file)
--- a/documentation/test_doxygen/compound_namespace_members_in_file_scope/File.h
+++ b/documentation/test_doxygen/compound_namespace_members_in_file_scope/File.h
@@ -12,6 +12,13 @@ Detailed function docs.
 */
 void foo();
 
+/**
+@overload
+
+Function overload with no brief.
+*/
+void foo(float);
+
 /** @brief Function with just a brief */
 void fooBrief();
 
@@ -66,6 +73,13 @@ Detailed function docs.
 */
 void foo();
 
+/**
+@overload
+
+Function overload with no brief.
+*/
+void foo(float);
+
 /** @brief Function with just a brief */
 void fooBrief();
 

diff --git a/documentation/test_doxygen/compound_namespace_members_in_file_scope/File_8h.html b/documentation/test_doxygen/compound_namespace_members_in_file_scope/File_8h.html
index ab989fff6620ceb176bae78cf3e3e441295b795b..73dafd8d93af867a910e2940e521e0df1de70ca0 100644 (file)
--- a/documentation/test_doxygen/compound_namespace_members_in_file_scope/File_8h.html
+++ b/documentation/test_doxygen/compound_namespace_members_in_file_scope/File_8h.html
@@ -95,6 +95,10 @@
               <span class="m-doc-wrap-bumper">void <a href="namespaceNamespace.html#a0f1fe1a972c7c4196988a1bdde63ec77" class="m-doc">foo</a>(</span><span class="m-doc-wrap">)</span>
             </dt>
             <dd>A function.</dd>
+            <dt>
+              <span class="m-doc-wrap-bumper">void <a href="namespaceNamespace.html#aeb6c50900bdadb39b7e953762a0515ba" class="m-doc">foo</a>(</span><span class="m-doc-wrap">float)</span>
+            </dt>
+            <dd></dd>
             <dt>
               <span class="m-doc-wrap-bumper">void <a href="namespaceNamespace.html#a25c0cb6154508312ca2f28fdab944741" class="m-doc">fooBrief</a>(</span><span class="m-doc-wrap">)</span>
             </dt>
@@ -103,6 +107,10 @@
               <span class="m-doc-wrap-bumper">void <a href="#a3d859e95e6eb8b4da1c10b6417ab8e9b" class="m-doc">foo</a>(</span><span class="m-doc-wrap">)</span>
             </dt>
             <dd>A function.</dd>
+            <dt>
+              <span class="m-doc-wrap-bumper">void <a href="#adf742e3b30e4d430f8a500ebfae7aea2" class="m-doc">foo</a>(</span><span class="m-doc-wrap">float)</span>
+            </dt>
+            <dd></dd>
             <dt id="a9ca3f6e800be14b033c364187b444b2f">
               <span class="m-doc-wrap-bumper">void <a href="#a9ca3f6e800be14b033c364187b444b2f" class="m-doc-self">fooBrief</a>(</span><span class="m-doc-wrap">)</span>
             </dt>
@@ -179,6 +187,12 @@
             <p>A function.</p>
 <p>Detailed function docs.</p>
           </div></section>
+          <section class="m-doc-details" id="adf742e3b30e4d430f8a500ebfae7aea2"><div>
+            <h3>
+              <span class="m-doc-wrap-bumper">void </span><span class="m-doc-wrap"><span class="m-doc-wrap-bumper"><a href="#adf742e3b30e4d430f8a500ebfae7aea2" class="m-doc-self">foo</a>(</span><span class="m-doc-wrap">float)</span></span>
+            </h3>
+<p>This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.</p><p>Function overload with no brief.</p>
+          </div></section>
         </section>
         <section>
           <h2>Variable documentation</h2>

diff --git a/documentation/test_doxygen/compound_namespace_members_in_file_scope/namespaceNamespace.html b/documentation/test_doxygen/compound_namespace_members_in_file_scope/namespaceNamespace.html
index 2b5c483813320dd19439b390c55a171274b41036..a141a42e9921bff98d472aba0120242990c59a08 100644 (file)
--- a/documentation/test_doxygen/compound_namespace_members_in_file_scope/namespaceNamespace.html
+++ b/documentation/test_doxygen/compound_namespace_members_in_file_scope/namespaceNamespace.html
@@ -71,6 +71,10 @@
               <span class="m-doc-wrap-bumper">void <a href="#a0f1fe1a972c7c4196988a1bdde63ec77" class="m-doc">foo</a>(</span><span class="m-doc-wrap">)</span>
             </dt>
             <dd>A function.</dd>
+            <dt>
+              <span class="m-doc-wrap-bumper">void <a href="#aeb6c50900bdadb39b7e953762a0515ba" class="m-doc">foo</a>(</span><span class="m-doc-wrap">float)</span>
+            </dt>
+            <dd></dd>
             <dt id="a25c0cb6154508312ca2f28fdab944741">
               <span class="m-doc-wrap-bumper">void <a href="#a25c0cb6154508312ca2f28fdab944741" class="m-doc-self">fooBrief</a>(</span><span class="m-doc-wrap">)</span>
             </dt>
@@ -130,6 +134,12 @@
             <p>A function.</p>
 <p>Detailed function docs.</p>
           </div></section>
+          <section class="m-doc-details" id="aeb6c50900bdadb39b7e953762a0515ba"><div>
+            <h3>
+              <span class="m-doc-wrap-bumper">void Namespace::<wbr /></span><span class="m-doc-wrap"><span class="m-doc-wrap-bumper"><a href="#aeb6c50900bdadb39b7e953762a0515ba" class="m-doc-self">foo</a>(</span><span class="m-doc-wrap">float)</span></span>
+            </h3>
+<p>This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.</p><p>Function overload with no brief.</p>
+          </div></section>
         </section>
         <section>
           <h2>Variable documentation</h2>