[python] Use wire names in TypedDict docstrings

.chronus/changes/copilot-fix-typeddict-camelcase-docstrings-2026-6-24-17-40-35.md

@@ -0,0 +1,7 @@
+---
+changeKind: fix
+packages:
+  - "@typespec/http-client-python"
+---
+
+Use wire names in TypedDict docstrings

packages/http-client-python/generator/pygen/codegen/serializers/model_serializer.py

@@ -77,15 +77,18 @@ def _documentation_string(
     prop: Property, description_keyword: str, docstring_type_keyword: str, **kwargs: Any
 ) -> list[str]:
     retval: list[str] = []
-    sphinx_prefix = f":{description_keyword} {prop.client_name}:"
+    doc_name = (
+        prop.wire_name if kwargs.get("serialize_namespace_type") == NamespaceType.TYPES_FILE else prop.client_name
+    )
+    sphinx_prefix = f":{description_keyword} {doc_name}:"
     description = prop.description(is_operation_file=False).replace("\\", "\\\\")
     retval.append(f"{sphinx_prefix} {description}" if description else sphinx_prefix)
     # In the types file, use type_annotation (the serialized form) for docstrings
     if kwargs.get("serialize_namespace_type") == NamespaceType.TYPES_FILE:
         doc_type = prop.type.type_annotation(**kwargs)
     else:
         doc_type = prop.type.docstring_type(**kwargs)
-    retval.append(f":{docstring_type_keyword} {prop.client_name}: {doc_type}")
+    retval.append(f":{docstring_type_keyword} {doc_name}: {doc_type}")
     return retval
 
 

packages/http-client-python/tests/unit/test_typeddict.py

@@ -368,6 +368,36 @@ def test_models_mode_typeddict_serialize_contains_class():
     assert "TypedDict" in output
 
 
+def test_models_mode_typeddict_docstring_uses_wire_name():
+    """TypedDict docstrings in types.py should document the on-the-wire property name."""
+    code_model = _make_code_model(models_mode="typeddict")
+    string_type = build_type({"type": "string"}, code_model)
+    model = TypedDictModelType(
+        yaml_data={"name": "Foo", "type": "model", "snakeCaseName": "foo", "usage": 2},
+        code_model=code_model,
+        properties=[
+            Property(
+                yaml_data={
+                    "wireName": "paramName",
+                    "clientName": "param_name",
+                    "optional": True,
+                },
+                code_model=code_model,
+                type=string_type,
+            )
+        ],
+    )
+    code_model.model_types = [model]
+
+    env = _make_env()
+    output = TypesSerializer(code_model=code_model, env=env, models=[model]).serialize()
+
+    assert ":ivar paramName:" in output
+    assert ":vartype paramName: str" in output
+    assert ":ivar param_name:" not in output
+    assert ":vartype param_name:" not in output
+
+
 def test_types_file_has_no_named_unions():
     """Serialized types.py should not contain named union definitions."""
     code_model = _make_code_model(models_mode="dpg")