[issue35449] documenting objects

Change by Karthikeyan Singaravelan : -- nosy: +rhettinger ___ Python tracker ___ ___ Python-bugs-list mailing list Unsubscribe:

[issue35449] documenting objects

Terry J. Reedy added the comment: The reason that modules, classes, and functions need a special rule for assigning the .__doc__ attribute is that one cannot get a reference to the module, class, or function within the body of its definition. And putting the docstring at the top of a file

[issue35449] documenting objects

Stefan Seefeld added the comment: ad 3) sorry, I picked a bad example - I didn't mean to suggest that immutable objects should in fact become mutable by modifying their `__doc__` attribute. ad 1) good, glad to hear that. ad 2) fine. In fact, I'm not even proposing that per-instance

[issue35449] documenting objects

Steven D'Aprano 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

[issue35449] documenting objects

Stefan Seefeld added the comment: On 2018-12-09 19:48, Karthikeyan Singaravelan wrote: > There was a related proposal in > https://www.python.org/dev/peps/pep-0258/#attribute-docstrings Right, but that was rejected (for unrelated reasons). The idea itself was rejected by Guido

[issue35449] documenting objects

Karthikeyan Singaravelan added the comment: There was a related proposal in https://www.python.org/dev/peps/pep-0258/#attribute-docstrings -- ___ Python tracker ___

[issue35449] documenting objects

Stefan Seefeld added the comment: On 2018-12-09 18:35, Steven D'Aprano wrote: > Steven D'Aprano 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)

[issue35449] documenting objects

Steven D'Aprano 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

[issue35449] documenting objects

Stefan Seefeld added the comment: Exactly ! I'm fully aware of the ubiquity of objects in Python, and it is for that reason that I had naively expected `pydoc` to simply DoTheRightThing when encountering an object containing a `__doc__` attribute. rather than only working for types and

[issue35449] documenting objects

Steven D'Aprano added the comment: Minor note on terminology: classes and functions are themselves objects. I think that help() (or in particular PyDoc in general) should support any instance with a __doc__ attribute. Its failure to do so is causing pain, see #12154. -- nosy:

[issue35449] documenting objects

Change by Karthikeyan Singaravelan : -- nosy: +xtreak ___ Python tracker ___ ___ Python-bugs-list mailing list Unsubscribe:

[issue35449] documenting objects

New submission from Stefan Seefeld : On multiple occasions I have wanted to add documentation not only to Python classes and functions, but also instance variables. This seems to involve (at least) two orthogonal questions: 1) what is the proper syntax to associate documentation (docstrings