From 0924ae016723a75ac0e39af25a9821436b89f556 Mon Sep 17 00:00:00 2001
From: Yuri Sizov <yuris@humnom.net>
Date: Wed, 8 Nov 2023 15:16:35 +0100
Subject: [PATCH] Resolve collisions in reference anchors added for methods

While the anchors themselves were sufficiently unique,
when converted to HTML all underscore characters are
replaced. This created collisions between, say, Object._get and
Object.get, where the latter would get a generic unique
anchor identifier, e.g. id1.
---
 doc/tools/make_rst.py | 42 ++++++++++++++++++++++++++++--------------
 1 file changed, 28 insertions(+), 14 deletions(-)

diff --git a/doc/tools/make_rst.py b/doc/tools/make_rst.py
index e62b3d56d7f..6db11e4b29a 100755
--- a/doc/tools/make_rst.py
+++ b/doc/tools/make_rst.py
@@ -1224,7 +1224,11 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir:
                 # Create method signature and anchor point.
 
                 if i == 0:
-                    f.write(f".. _class_{class_name}_method_{m.name}:\n\n")
+                    method_qualifier = ""
+                    if m.name.startswith("_"):
+                        method_qualifier = "private_"
+
+                    f.write(f".. _class_{class_name}_{method_qualifier}method_{m.name}:\n\n")
 
                 f.write(".. rst-class:: classref-method\n\n")
 
@@ -1388,6 +1392,11 @@ def make_method_signature(
             for parameter in definition.parameters:
                 out += f"_{parameter.type_name.type_name}"
             out += f">` "
+        elif ref_type == "method":
+            ref_type_qualifier = ""
+            if definition.name.startswith("_"):
+                ref_type_qualifier = "private_"
+            out += f":ref:`{definition.name}<class_{class_def.name}_{ref_type_qualifier}{ref_type}_{definition.name}>` "
         else:
             out += f":ref:`{definition.name}<class_{class_def.name}_{ref_type}_{definition.name}>` "
     else:
@@ -1915,19 +1924,21 @@ def format_text_block(
                             )
 
                         # Default to the tag command name. This works by default for most tags,
-                        # but member and theme_item have special cases.
+                        # but method, member, and theme_item have special cases.
                         ref_type = "_{}".format(tag_state.name)
-                        if tag_state.name == "member":
-                            ref_type = "_property"
 
                         if target_class_name in state.classes:
                             class_def = state.classes[target_class_name]
 
-                            if tag_state.name == "method" and target_name not in class_def.methods:
-                                print_error(
-                                    f'{state.current_class}.xml: Unresolved method reference "{link_target}" in {context_name}.',
-                                    state,
-                                )
+                            if tag_state.name == "method":
+                                if target_name.startswith("_"):
+                                    ref_type = "_private_method"
+
+                                if target_name not in class_def.methods:
+                                    print_error(
+                                        f'{state.current_class}.xml: Unresolved method reference "{link_target}" in {context_name}.',
+                                        state,
+                                    )
 
                             elif tag_state.name == "constructor" and target_name not in class_def.constructors:
                                 print_error(
@@ -1941,11 +1952,14 @@ def format_text_block(
                                     state,
                                 )
 
-                            elif tag_state.name == "member" and target_name not in class_def.properties:
-                                print_error(
-                                    f'{state.current_class}.xml: Unresolved member reference "{link_target}" in {context_name}.',
-                                    state,
-                                )
+                            elif tag_state.name == "member":
+                                ref_type = "_property"
+
+                                if target_name not in class_def.properties:
+                                    print_error(
+                                        f'{state.current_class}.xml: Unresolved member reference "{link_target}" in {context_name}.',
+                                        state,
+                                    )
 
                             elif tag_state.name == "signal" and target_name not in class_def.signals:
                                 print_error(