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.

documentation/doxygen.py

@@ -2121,11 +2121,31 @@ def is_identifier(a): return a == '_' or a.isalnum()
     # 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 is_identifier(a): return a == '_' or a.isalnum()
             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'

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();
 

documentation/test_doxygen/compound_namespace_members_in_file_scope/File_8h.html

@@ -95,6 +95,10 @@ <h2><a href="#func-members">Functions</a></h2>
               <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 @@ <h2><a href="#func-members">Functions</a></h2>
               <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 @@ <h3>
             <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>

documentation/test_doxygen/compound_namespace_members_in_file_scope/namespaceNamespace.html

@@ -71,6 +71,10 @@ <h2><a href="#func-members">Functions</a></h2>
               <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 @@ <h3>
             <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>