Re: Python Documentation Standards
Steven Bethard wrote: Colin J. Williams wrote: Doc strings provide us with a great opportunity to illuminate our code. In the example below, __init__ refers us to the class's documentation, but the class doc doesn't help much. It doesn't? print list.__doc__ list() - new list list(sequence) - new list initialized from sequence's items What is it you were hoping to see in constructor documentation? STeVe You are right, I didn't dig far enough. Colin W. -- http://mail.python.org/mailman/listinfo/python-list
Python Documentation Standards
Doc strings provide us with a great opportunity to illuminate our code. In the example below, __init__ refers us to the class's documentation, but the class doc doesn't help much. Are there any guideline which cover such things? PEP 8 http://www.python.org/doc/peps/pep-0008/ has general advice. PEP 257 http://www.python.org/doc/peps/pep-0257/ provides more detailed advice. list provides a trivial example because it is very well documented elsewhere but it does provide a template for others. Colin W. Colin W. list.__init__.__doc__ 'x.__init__(...) initializes x; see x.__class__.__doc__ for signature' list.__new__.__doc__ 'T.__new__(S, ...) - a new object with type S, a subtype of T' list.__class__.__doc__ type(object) - the object's type\ntype(name, bases, dict) - a new type -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation Standards
Colin J. Williams wrote: Doc strings provide us with a great opportunity to illuminate our code. In the example below, __init__ refers us to the class's documentation, but the class doc doesn't help much. It doesn't? print list.__doc__ list() - new list list(sequence) - new list initialized from sequence's items What is it you were hoping to see in constructor documentation? STeVe -- http://mail.python.org/mailman/listinfo/python-list
Re: Python Documentation Standards
Steven Bethard wrote: Colin J. Williams wrote: Doc strings provide us with a great opportunity to illuminate our code. In the example below, __init__ refers us to the class's documentation, but the class doc doesn't help much. It doesn't? print list.__doc__ list() - new list list(sequence) - new list initialized from sequence's items What is it you were hoping to see in constructor documentation? STeVe How about this?: print list.__doc__ list() - new list list(sequence) - new list initialized from sequence's items See http://docs.python.org/lib/built-in-funcs.html#l2h-44 although it would be better if the online docs had a more permanent looking anchor. -- http://mail.python.org/mailman/listinfo/python-list
