mitmproxy / mitmproxy/pdoc

Incorrect documentation when a method and its return type share the same name

Open
#809 3 comments 0 reactions 0 assignees View on GitHub

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:
  1. Python code in dog.py to be used with pdoc
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()
  1. Run: pdoc ./dog.py -o doc
  2. Examine the issue in the pdoc output
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.