On Jan 22, 2020, at 13:01, Christopher Barker
On Tue, Jan 21, 2020 at 12:55 PM
wrote: Currently, there is no way to add docstrings to fields in dataclasses. PEP257 talks about attribute docstrings (a string literal following an assignment), but these are visual only and not accessible at runtime. My suggestion would be a simple `doc` or `docstring` parameter to dataclasses.field(). Currently the best way to get anything close to this is using metadata, which is much clunkier: `dataclasses.field(metadata={'docstring': 'my description'})`
My first thought is "sure, why not", but then I thought a bit more, and I"m not so sure.
Instance attributes are exactly the same issue as module contents. You can’t apply a docstring to the constants and variables in a module either. Why? Because you can’t attach anything to a variable, because a variable isn’t a thing in the language. You can only attach stuff to values. So a docstring attached to "x = 42" would change the help for the number 42 (everywhere in the program), not the variable x, and that would be silly. The reason it makes sense for modules’ functions (and modules’ classes, and classes’ methods and inner classes—and descriptors) is that there aren’t any other instances of that function value anywhere else in the program, there’s just that one. If anyone has that value, they have that actual function, and they want that function’s docstring. This isn’t just acceptable, it’s necessary. Consider a method object like spam.eggs; it has no idea that you got the function value from a variable named eggs in the spam object’s type, it just has a reference to that same function value in a variable named __func__ in the method object (which obviously nobody has attached a docstring to). But because docstrings are on values rather than variables, self.__func__.__doc__ is the right docstring. I think Ricky’s answer is promising. We already have code to generate help for a module that includes all of its attributes. That doesn’t make sense for class instances in general, but it does make sense for dataclass instances. And extending it to also include some string for each one makes sense. I wouldn’t be surprised if such things already existing for Django thingies and attrs classes.