This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Author stefan
Recipients stefan, steven.daprano, xtreak
Date 2018-12-10.00:30:02
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <874978ef-8bff-ca02-1d0c-99e5ddf65e97@seefeld.name>
In-reply-to <20181209233450.GX13061@ando.pearwood.info>
Content
On 2018-12-09 18:35, Steven D'Aprano wrote:
> Steven D'Aprano <steve+python@pearwood.info> added the comment:
>
>> Is there any discussion concerning what syntax might be used for 
>> docstrings associated with objects ?
> I don't know about PyDoc in general, but I would expect help(obj) to 
> just use obj.__doc__ which will return the instance docstring if it 
> exists, and if not, the type docstring (if it exists). No new syntax is 
> required, the standard ``help(obj)`` is sufficient.

That's why I distinguished between points 1) and 2) in my original mail:
The syntax is about how certain tokens in the parse tree are associated
as "docstring" with a given object (i.e., point 1), while the pydoc's
behaviour (to either accept any `__doc__` attributes, or only those of
specific types of objects) is entirely orthogonal to that (thus point 2).

I now understand that the current `pydoc` behaviour is considered
erroneous, and it sounds like a fix would be simple and focused in scope.

>> (There seem to be some partial 
>> solutions added on top of the Python parser (I think `epydoc` offered 
>> one), but it would be nice to have a built-in solution to avoid having 
>> to re-invent wheels.
> Are you suggesting we need new syntax to automatically assign docstrings 
> to instances? I don't think we do.

No, I'm not suggesting that. I'm suggesting that within the current
syntax, some additional semantic rules might be required to bind
comments (or strings) to objects as "docstrings". For example:

```

foo = 123

"""This is foo's docstring"""

```

might be one convention to add a docstring to a variable.

```

foo = 123

# This is foo's docstring

```

might be another.

None of this is syntactically new, but the construction of the AST from
the parse tree is. (I have seen both of these conventions used in custom
tools to associate documentation to variables, which of course requires
hacking into the parser internals, to add the given docstring to the
object's `__doc__` attribute.

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.
History
Date User Action Args
2018-12-10 00:30:02stefansetrecipients: + stefan, steven.daprano, xtreak
2018-12-10 00:30:02stefanlinkissue35449 messages
2018-12-10 00:30:02stefancreate