Steven D'Aprano <steve+pyt...@pearwood.info> added the comment:
I asked:
> > Are you suggesting we need new syntax to automatically assign docstrings
> > to instances?
Stefan replied:
> No, I'm not suggesting that.
And then immediately went on to suggest new syntax for automatically
binding a string to objects as docstrings. I am amused :-)
Whether you want to call it "new semantics for existing syntax" or "new
syntax" is a matter of terminology. The point is, you are suggesting
something that requires dedicated support from the interpreter, as
opposed to merely writing some Python code.
> I'm suggesting that within the current
> syntax, some additional semantic rules might be required to bind
> comments (or strings) to objects as "docstrings".
To my mind, it makes sense to have dedicated docstring syntax for
classes, modules and functions: I expect that they will make up in
excess of 95% of use-cases for docstrings. In this case, special cases
*are* special enough to change the rules.
But for the rare(?) cases of wanting to add docstrings to arbitrary
instances, I don't think it is justified to have dedicated syntax to do
it. It's easy enough and more than flexible enough to just do an
instance attribute assignment:
instance.__doc__ = """This is the instance docstring."""
I strongly oppose any suggestion that *comments* be treated as code:
> foo = 123
> # This is foo's docstring
Deleting comments shouldn't make have any runtime effect on the code,
but in this case it would. (I'm willing to make an exception for the
optional encoding cookie at the beginning of modules, as a rather
special case.)
So I think there are three related but separate issues here:
1. help(obj) and possibly PyDoc in general ought to support per-instance
docstrings. I think that is uncontroversial and we just need somebody to
do the work to make it happen.
2. Add special syntactic sugar to automatically associate a string with
arbitrary instances as a docstring. I think that's overkill and
unnecessary, but I'd be willing to be convinced otherwise.
3. Your examples suggest that even built-in immutable objects like ints
should be able to take docstrings. I don't think that idea is going to
fly, but I'm also not sure how serious you are about that. It runs into
the problem that small ints and certain strings are cached, so your
docstring could clobber my docstring. It is also going to require the
addition of an extra attribute slot to every int, str, etc for the
docstring, even if 99.999% of them never use it.
> It would be great to establish a convention for this, so in the future
> tools don't have to invent their own (non-portable) convention.
``instance.__doc__ = "docstring"`` seems pretty portable to me :-)
----------
_______________________________________
Python tracker <rep...@bugs.python.org>
<https://bugs.python.org/issue35449>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe:
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
