On 12/6/2013 5:46 AM, Steven D'Aprano wrote:
On Fri, Dec 06, 2013 at 07:28:57AM +0100, Gregory Salvan wrote:
class MyObject(metaclass=ObjectSpec): ''' MyObject doc''' 'attr1 contains something' attr1 = None 'attr2 contains something' attr2 = str 'method1 do something' method1 = NotImplementedMethod('self', 'arg1', kwarg1=str)I really don't like the idea of extending the docstring syntax to arbitrary objects.
> ...
Another issue is that many objects (particularly built-ins) cannot take additional attributes. So where are you going to attach the docstrings?
For data attributes, which are usually mutable, it should be attached to the attribute *concept*, which is represented by the name, rather than the current but usually changeable value. Values are usually already documented either by a value representation or a docstring. This could be done with a string subclass that is used as needed.
For methods, the value is nearly always constant. When multiple methods share the same function, they usually also share the same name, and represent the same concept.
A half-way measure would be to extend help() (pydoc, I guess) to recognize the same attribute comment conventions as Sphinx autodoc when source is available, as it usually is. If we do this, I think the conventions should be 'blessed' in an info pep. Docstrings are seldom needed for runtime execution, which is why we have an option to remove them.
-- Terry Jan Reedy _______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
