Stefan Seefeld <ste...@seefeld.name> added the comment:
On 2018-12-09 18:35, Steven D'Aprano wrote: > Steven D'Aprano <steve+pyt...@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. ---------- _______________________________________ 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
