From 9160cb1af5bae144c9865c366cd58b0eb13e0196 Mon Sep 17 00:00:00 2001
From: Michael Carlstrom <rmc@carlstrom.com>
Date: Sun, 8 Dec 2024 14:32:59 -0500
Subject: [PATCH] comments and function name cleanup

---
 include/pybind11/cast.h    |  2 +-
 include/pybind11/pytypes.h |  9 +++------
 tests/test_pytypes.cpp     | 10 +++++-----
 3 files changed, 9 insertions(+), 12 deletions(-)

diff --git a/include/pybind11/cast.h b/include/pybind11/cast.h
index 162e1884e..1274eb89f 100644
--- a/include/pybind11/cast.h
+++ b/include/pybind11/cast.h
@@ -1334,7 +1334,7 @@ object object_or_cast(T &&o) {
 // Written here so make_caster<T> can be used
 template <typename D>
 template <typename T>
-str_attr_accessor object_api<D>::attr_with_type(const char *key) const {
+str_attr_accessor object_api<D>::attr_with_type_hint(const char *key) const {
     annotations()[key] = make_caster<T>::name.text;
     return {derived(), key};
 }
diff --git a/include/pybind11/pytypes.h b/include/pybind11/pytypes.h
index 89afe2213..4435ecf98 100644
--- a/include/pybind11/pytypes.h
+++ b/include/pybind11/pytypes.h
@@ -114,9 +114,9 @@ public:
     str_attr_accessor attr(const char *key) const;
 
 #if defined(PYBIND11_CPP17)
-    // attr_with_type is implemented in cast.h:
+    // attr_with_type_hint is implemented in cast.h:
     template <typename T>
-    str_attr_accessor attr_with_type(const char *key) const;
+    str_attr_accessor attr_with_type_hint(const char *key) const;
 #endif
     /** \rst
         Matches * unpacking in Python, e.g. to unpack arguments out of a ``tuple``
@@ -2567,16 +2567,13 @@ str_attr_accessor object_api<D>::doc() const {
 }
 
 template <typename D>
-// Always a dict
-// https://docs.python.org/3/howto/annotations.html#accessing-the-annotations-dict-of-an-object-in-python-3-9-and-older
 object object_api<D>::annotations() const {
-// Python 3.8, 3.9
 #if PY_MAJOR_VERSION == 3 && PY_MINOR_VERSION <= 9
+// https://docs.python.org/3/howto/annotations.html#accessing-the-annotations-dict-of-an-object-in-python-3-9-and-older
     if (!hasattr(derived(), "__annotations__")) {
         setattr(derived(), "__annotations__", dict());
     }
     return attr("__annotations__");
-// Python 3.10+
 #else
     return getattr(derived(), "__annotations__", dict());
 #endif
diff --git a/tests/test_pytypes.cpp b/tests/test_pytypes.cpp
index e2cca7560..02ad90559 100644
--- a/tests/test_pytypes.cpp
+++ b/tests/test_pytypes.cpp
@@ -1000,8 +1000,8 @@ TEST_SUBMODULE(pytypes, m) {
 #endif
 
 #if defined(PYBIND11_CPP17)
-    m.attr_with_type<py::typing::List<int>>("list_int") = py::list();
-    m.attr_with_type<py::typing::Set<py::str>>("set_str") = py::set();
+    m.attr_with_type_hint<py::typing::List<int>>("list_int") = py::list();
+    m.attr_with_type_hint<py::typing::Set<py::str>>("set_str") = py::set();
 
     struct Empty {};
     py::class_<Empty>(m, "EmptyAnnotationClass");
@@ -1011,10 +1011,10 @@ TEST_SUBMODULE(pytypes, m) {
         py::dict dict_str_int;
     };
     auto point = py::class_<Point>(m, "Point");
-    point.attr_with_type<float>("x");
-    point.attr_with_type<py::typing::Dict<py::str, int>>("dict_str_int") = py::dict();
+    point.attr_with_type_hint<float>("x");
+    point.attr_with_type_hint<py::typing::Dict<py::str, int>>("dict_str_int") = py::dict();
 
-    m.attr_with_type<py::typing::Final<int>>("CONST_INT") = 3;
+    m.attr_with_type_hint<py::typing::Final<int>>("CONST_INT") = 3;
     m.attr("defined_PYBIND11_CPP17") = true;
 #else
     m.attr("defined_PYBIND11_CPP17") = false;