Incorrect documentation when a method and its return type share the same name
Open
Nobody has claimed this yet.
bug
- Dominant language
- Python
- Stars
- 2.5k
- Forks
- 228
- PR merge metrics
- No merged PRs in 30d
Description
Problem Description
Encountering incorrect documentation when a method and its return type share the same name. For example, consider the following code:
def Dog(self) -> Dog:
The generated documentation displays:
Dog: <property object at 0x7ffff63607c0>
Steps to reproduce the behavior:
- Python code in
dog.pyto be used withpdoc
from __future__ import annotations
class Factory:
def __init__(self) -> None:
self._dog: Dog = Dog("my_dog")
@property
def Dog(self) -> Dog:
return self._dog
class Dog:
def __init__(self, name: str) -> None:
self._name: str = name
@property
def Name(self) -> str:
return self._name
def main() -> None:
factory: Factory = Factory()
dog: Dog = factory.Dog
print(dog.Name)
main()
- Run:
pdoc ./dog.py -o doc - Examine the issue in the
pdocoutput
dog
class Factory:
Dog: <property object at 0x7ffff6367d10>
class Dog:
Dog(name: str)
Name: str
def main() -> None:
System Information
% pdoc --version
pdoc: 15.0.3
Python: 3.9.6
Platform: Linux-4.12.14-122.201-default-x86_64-with-glibc2.22
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by creating the dog.py example from the issue and running pdoc ./dog.py -o doc with the reported Python and pdoc versions. Inspect the generated documentation for Factory.Dog and trace the relevant pdoc documentation-generation entry point. Done means the method's return type is rendered as Dog rather than a property object while the surrounding API documentation remains correct.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100