Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation for _serialize/_deserialize shows parent class docstring #2307

Open
AbdealiLoKo opened this issue Sep 16, 2024 · 2 comments
Open
Labels

Comments

@AbdealiLoKo
Copy link

AbdealiLoKo commented Sep 16, 2024

I was looking at the docs for Enum._serialize and got confused by what it was saying:

Serializes value to a basic Python datatype. Noop by default

And then realized this is the docstring from fields.Field and is meant for the developer who is subclassing fields.Field !
Got a bit confused there, not sure if this is the expected documentation :)

image

@AbdealiLoKo AbdealiLoKo changed the title Documentation for _serialize/_deserialize shows parent class docs Documentation for _serialize/_deserialize shows parent class docstring Sep 16, 2024
@sloria sloria added the docs label Sep 16, 2024
@sloria
Copy link
Member

sloria commented Sep 16, 2024

Ah, i can see how that's confusing. That certainly isn't intentional. PRs welcome!

@lafrech
Copy link
Member

lafrech commented Oct 10, 2024

The right thing to do would be not to document those methods at all IMHO. There is no added value, since they all have the same signature. The only thing we really want to see here is the class docstring of each field, which describes what it does and what its parameters are. The rest is internals.

There seems to be a lot of automatic stuff going on, I don't know when it started to happen. For instance, the Number field doc shows float methods, which is irrelevant.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

No branches or pull requests

3 participants