Re: [Python-Dev] docstring before function declaration
Rule #1: If the docstring is the first line of a module, it's the module's docstring. Rule #2: If the docstring comes right before a class/function, it's that class/function's docstring.
How do you distinguish between a docstring at the top of a module that's immediately followed by a function? Is it the module docstring or the function docstring?
It's both. The docstring would be assigned to both the module and the function. This is a *good* thing when there is a module with only one function in it. i.e. there should only be one docstring for both, and this saves repetition of that docstring. If a programmer wanted a docstring for the function but not the module, a blank first line would do the trick. A docstring for the module but not the function? Put a blank line between the module's docstring and the function. --Nick Jacobson __________________________________ Do you Yahoo!? Yahoo! Small Business - Try our new resources site! http://smallbusiness.yahoo.com/resources/
On Monday 21 March 2005 20:08, Nicholas Jacobson wrote:
How do you distinguish between a docstring at the top of a module that's immediately followed by a function? Is it the module docstring or the function docstring?
It's both. The docstring would be assigned to both the module and the function. This is a *good* thing when there is a module with only one function in it. i.e. there should only be one docstring for both, and this saves repetition of that docstring.
If a programmer wanted a docstring for the function but not the module, a blank first line would do the trick. A docstring for the module but not the function? Put a blank line between the module's docstring and the function.
Yuk. This is magic taken to a ridiculous level. Note that "blank lines" currently have no meaning in Python, and adding a meaning to them is not my idea of a good thing. -- Anthony Baxter <anthony@interlink.com.au> It's never too late to have a happy childhood.
Nicholas Jacobson wrote:
If a programmer wanted a docstring for the function but not the module, a blank first line would do the trick. A docstring for the module but not the function? Put a blank line between the module's docstring and the function.
-1 on all this making of blank lines significant. Currently I can leave some space before/after a docstring without breaking anything. This can help readability, especially for class docstrings. -- Greg Ewing, Computer Science Dept, +--------------------------------------+ University of Canterbury, | A citizen of NewZealandCorp, a | Christchurch, New Zealand | wholly-owned subsidiary of USA Inc. | greg.ewing@canterbury.ac.nz +--------------------------------------+
participants (3)
-
Anthony Baxter -
Greg Ewing -
Nicholas Jacobson