<div dir="ltr"><div dir="ltr"><div>(answers above and below the quoting)</div><div><br></div><div>I like the idea of documenting attributes, but we shouldn't force the user to use __slots__ as that has significant side effects and is rarely something people should bother to use.  There are multiple types of attributes.  class and instance.  but regardless of where they are initialized, they all define the API shape of a class (or instance).</div><div><br></div><div>Q: Where at runtime regardless of syntax chosen would such docstrings live?  One (of many) common conventions today is to just put them into an Attributes: or similar section of the class docstring.  We could actually do that automatically by appending a section to the class docstring, but that unstructures the data enshrining one format and could break existing code for the users of the few but existing APIs that treat docstrings as structured runtime data instead of documentation if someone were to try and use attribute docstrings on subclasses of those library types.  (ply does this, I believe some database abstraction APIs do as well).</div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Wed, Mar 20, 2019 at 12:41 AM Serhiy Storchaka <<a href="mailto:storchaka@gmail.com">storchaka@gmail.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">19.03.19 20:55, Raymond Hettinger пише:<br>
> I'm working on ways to make improve help() by giving docstrings to member objects.<br>
> <br>
> One way to do it is to wait until after the class definition and then make individual, direct assignments to __doc__ attributes.This way widely the separates docstrings from their initial __slots__ definition.   Working downstream from the class definition feels awkward and doesn't look pretty.<br>
> <br>
> There's another way I would like to propose¹.  The __slots__ definition already works with any iterable including a dictionary (the dict values are ignored), so we could use the values for the  docstrings.<br>
<br>
I think it would be nice to separate docstrings from the bytecode. This <br>
would be allow to have several translated sets of docstrings and load an <br>
appropriate set depending on user preferences. This would help in <br>
teaching Python.<br>
<br>
It is possible with docstrings of modules, classes, functions, methods <br>
and properties (created by using the decorator), because the compiler <br>
knows what string literal is a docstring. But this is impossible with <br>
namedtuple fields and any of the above ideas for slots.<br>
<br>
It would be nice to allow to specify docstrings for slots as for methods <br>
and properties. Something like in the following pseudocode:<br>
<br>
class NormalDist:<br>
     slot mu:<br>
        '''Arithmetic mean'''<br>
     slot sigma:<br>
         '''Standard deviation'''<br></blockquote><div> </div><div>I don't think adding a 'slot' keyword even if limited in scope to class body definition level is a good idea (very painful anytime we reserve a new word that is already used in code and APIs).</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
It would be also nice to annotate slots and add default values (used <br>
when the slot value was not set).<br>
<br>
class NormalDist:<br>
     mu: float = 0.0<br>
        '''Arithmetic mean'''<br>
     sigma: float = 1.0<br>
         '''Standard deviation'''<br>
<br></blockquote><div><br></div><div>Something along these lines is more interesting to me.  And could be applied to variables in _any_ scope.  though there wouldn't be a point in using a string in context where the name isn't bound to a class or module.</div><div><br></div><div>The best practice today remains "just use the class docstring to document your public class and instance attributes".  FWIW other languages tend to generate their documentation from code via comments rather than requiring a special in language runtime accessible syntax to declare it as documentation.</div><div><br></div><div>It feels like Python is diverging from the norm if we were encourage more of this __doc__ carried around at runtime implicit assignment than we already have.  I'm not convinced that is a good thing.</div><div><br></div><div>-gps</div></div></div></div>