OLD | NEW |
1 PEP: 257 | 1 PEP: 257 |
2 Title: Docstring Conventions | 2 Title: Docstring Conventions |
3 Version: $Revision$ | 3 Version: $Revision$ |
4 Last-Modified: $Date$ | 4 Last-Modified: $Date$ |
5 Author: David Goodger <goodger@python.org>, | 5 Author: David Goodger <goodger@python.org>, |
6 Guido van Rossum <guido@python.org> | 6 Guido van Rossum <guido@python.org> |
7 Discussions-To: doc-sig@python.org | 7 Discussions-To: doc-sig@python.org |
8 Status: Active | 8 Status: Active |
9 Type: Informational | 9 Type: Informational |
10 Content-Type: text/x-rst | 10 Content-Type: text/x-rst |
(...skipping 183 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
194 sensitive and the argument names can be used for keyword arguments, so | 194 sensitive and the argument names can be used for keyword arguments, so |
195 the docstring should document the correct argument names. It is best | 195 the docstring should document the correct argument names. It is best |
196 to list each argument on a separate line. For example:: | 196 to list each argument on a separate line. For example:: |
197 | 197 |
198 def complex(real=0.0, imag=0.0): | 198 def complex(real=0.0, imag=0.0): |
199 """Form a complex number. | 199 """Form a complex number. |
200 | 200 |
201 Keyword arguments: | 201 Keyword arguments: |
202 real -- the real part (default 0.0) | 202 real -- the real part (default 0.0) |
203 imag -- the imaginary part (default 0.0) | 203 imag -- the imaginary part (default 0.0) |
204 | |
205 """ | 204 """ |
206 if imag == 0.0 and real == 0.0: return complex_zero | 205 if imag == 0.0 and real == 0.0: |
| 206 return complex_zero |
207 ... | 207 ... |
208 | 208 |
209 The BDFL [3]_ recommends inserting a blank line between the last | 209 Unless the entire docstring fits on a line, place the closing quotes |
210 paragraph in a multi-line docstring and its closing quotes, placing | 210 on a line by themselves. This way, Emacs' ``fill-paragraph`` command |
211 the closing quotes on a line by themselves. This way, Emacs' | 211 can be used on it. |
212 ``fill-paragraph`` command can be used on it. | |
213 | 212 |
214 | 213 |
215 Handling Docstring Indentation | 214 Handling Docstring Indentation |
216 ------------------------------ | 215 ------------------------------ |
217 | 216 |
218 Docstring processing tools will strip a uniform amount of indentation | 217 Docstring processing tools will strip a uniform amount of indentation |
219 from the second and further lines of the docstring, equal to the | 218 from the second and further lines of the docstring, equal to the |
220 minimum indentation of all non-blank lines after the first line. Any | 219 minimum indentation of all non-blank lines after the first line. Any |
221 indentation in the first line of the docstring (i.e., up to the first | 220 indentation in the first line of the docstring (i.e., up to the first |
222 newline) is insignificant and removed. Relative indentation of later | 221 newline) is insignificant and removed. Relative indentation of later |
(...skipping 97 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
320 | 319 |
321 | 320 |
322 | 321 |
323 .. | 322 .. |
324 Local Variables: | 323 Local Variables: |
325 mode: indented-text | 324 mode: indented-text |
326 indent-tabs-mode: nil | 325 indent-tabs-mode: nil |
327 fill-column: 70 | 326 fill-column: 70 |
328 sentence-end-double-space: t | 327 sentence-end-double-space: t |
329 End: | 328 End: |
OLD | NEW |