[issue35449] documenting objects

[Steven D'Aprano]

Steven D'Aprano <steve+python at 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 <report at bugs.python.org>
<https://bugs.python.org/issue35449>
_______________________________________