Fix pointer-to-member-function param with ref-qualifier (#56219)

Summary:
Pull Request resolved: #56219

Changelog: [Internal]

Doxygen has a bug where it incorrectly embeds the parameter name of pointer-to-member-function parameters with ref-qualifiers (& or &&) into the type string instead of providing a separate <declname> element.

This caused the snapshot to output `R(folly::dynamic::*)() const asFoo&` instead of the correct `R(folly::dynamic::*asFoo)() const &`.

This diff detects the misplaced name in the type string and reconstructs the correct pointer-to-member declarator.

Reviewed By: cipolleschi

Differential Revision: D98123353

fbshipit-source-id: a3a92c5d3897721f0b97a232fdaa59379b408b29

Author: j-piasecki

scripts/cxx-api/parser/builders.py

@@ -377,6 +377,29 @@ def get_doxygen_params(
                     param_type[:insert_pos] + param_name + param_type[insert_pos:]
                 )
                 param_name = None
+        else:
+            # Doxygen bug: for pointer-to-member-function params with
+            # ref-qualifiers (& or &&), Doxygen incorrectly embeds the
+            # parameter name in the type string between cv-qualifiers
+            # and the ref-qualifier, and omits <declname> entirely:
+            #   <type>R(ns::*)() const asFoo &amp;</type>
+            # Detect this pattern and reconstruct the correct type:
+            #   R(ns::*asFoo)() const &
+            m = re.search(
+                r"(\([^)]*::\*\))"  # group 1: ptr-to-member declarator
+                r"(.+?)"  # group 2: param list + cv-qualifiers
+                r"\s+([a-zA-Z_]\w*)"  # group 3: misplaced identifier
+                r"\s*(&{1,2})\s*$",  # group 4: ref-qualifier
+                param_type,
+            )
+            if m:
+                param_type = (
+                    param_type[: m.end(1) - 1]  # up to ')' of (ns::*)
+                    + m.group(3)  # insert extracted name
+                    + param_type[m.end(1) - 1 : m.end(2)]  # ')' + params + cv-quals
+                    + " "
+                    + m.group(4)  # ref-qualifier
+                )
 
         qualifiers, core_type = extract_qualifiers(param_type)
         arguments.append((qualifiers, core_type, param_name, param_default))

scripts/cxx-api/tests/snapshots/should_handle_pointer_to_member_function_param_with_ref_qualifier/snapshot.api

@@ -0,0 +1,8 @@
+struct folly::dynamic {
+}
+
+
+template <typename R, typename... T>
+R test::jsArg(const folly::dynamic& arg, R(folly::dynamic::*asFoo)() const &, const T &... desc);
+template <typename R, typename... T>
+R test::jsArg(const folly::dynamic& arg, R(folly::dynamic::*asFoo)() const, const T &... desc);

scripts/cxx-api/tests/snapshots/should_handle_pointer_to_member_function_param_with_ref_qualifier/test.h

@@ -0,0 +1,23 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#pragma once
+
+namespace folly {
+
+struct dynamic {};
+
+} // namespace folly
+
+namespace test {
+
+template <typename R, typename... T>
+R jsArg(const folly::dynamic &arg, R (folly::dynamic::*asFoo)() const, const T &...desc);
+template <typename R, typename... T>
+R jsArg(const folly::dynamic &arg, R (folly::dynamic::*asFoo)() const &, const T &...desc);
+
+} // namespace test