PEP 257
"Paul Graves-DesLauriers" <[email protected]> Tue, 29 Dec 2020 17:58:18 -0800
| Newsgroups | gmane.comp.python.documentation |
|---|---|
| Organization | Dexmicro |
| Message-ID | <[email protected]> |
This is a multipart message in MIME format.
--===============5646173726735225868==
Content-Type: multipart/alternative;
boundary="----=_NextPart_000_0001_01D6DE0C.31E01070"
Content-Language: en-us
This is a multipart message in MIME format.
------=_NextPart_000_0001_01D6DE0C.31E01070
Content-Type: text/plain;
charset="us-ascii"
Content-Transfer-Encoding: 7bit
I would like clarification about the one-line docstring
<https://www.python.org/dev/peps/pep-0257/#id16> example.
The Notes say (fourth bullet):
The docstring is a phrase ending in a period. It prescribes the function or
method's effect as a command ("Do this", "Return that"), not as a
description; e.g. don't write "Returns the pathname ...".
However the docstring example for kos_root() is: """Return the pathname of
the KOS root directory."""
I've highlighted the areas that seem to contradict each other. Perhaps the
example should be updated to conform to the notes?
Thanks,
Paul
------=_NextPart_000_0001_01D6DE0C.31E01070
Content-Type: text/html;
charset="us-ascii"
Content-Transfer-Encoding: quoted-printable
<html xmlns:v=3D"urn:schemas-microsoft-com:vml" =
xmlns:o=3D"urn:schemas-microsoft-com:office:office" =
xmlns:w=3D"urn:schemas-microsoft-com:office:word" =
xmlns:m=3D"http://schemas.microsoft.com/office/2004/12/omml" =
xmlns=3D"http://www.w3.org/TR/REC-html40"><head><meta =
http-equiv=3DContent-Type content=3D"text/html; =
charset=3Dus-ascii"><meta name=3DGenerator content=3D"Microsoft Word 15 =
(filtered medium)"><style><!--
/* Font Definitions */
@font-face
{font-family:"Cambria Math";
panose-1:2 4 5 3 5 4 6 3 2 4;}
@font-face
{font-family:Calibri;
panose-1:2 15 5 2 2 2 4 3 2 4;}
/* Style Definitions */
p.MsoNormal, li.MsoNormal, div.MsoNormal
{margin:0in;
font-size:11.0pt;
font-family:"Calibri",sans-serif;}
a:link, span.MsoHyperlink
{mso-style-priority:99;
color:#0563C1;
text-decoration:underline;}
span.EmailStyle17
{mso-style-type:personal-compose;
font-family:"Calibri",sans-serif;
color:windowtext;}
.MsoChpDefault
{mso-style-type:export-only;}
@page WordSection1
{size:8.5in 11.0in;
margin:1.0in 1.0in 1.0in 1.0in;}
div.WordSection1
{page:WordSection1;}
--></style><!--[if gte mso 9]><xml>
<o:shapedefaults v:ext=3D"edit" spidmax=3D"1026" />
</xml><![endif]--><!--[if gte mso 9]><xml>
<o:shapelayout v:ext=3D"edit">
<o:idmap v:ext=3D"edit" data=3D"1" />
</o:shapelayout></xml><![endif]--></head><body lang=3DEN-US =
link=3D"#0563C1" vlink=3D"#954F72" style=3D'word-wrap:break-word'><div =
class=3DWordSection1><p class=3DMsoNormal><span =
style=3D'font-size:12.0pt'>I would like clarification about the <a =
href=3D"https://www.python.org/dev/peps/pep-0257/#id16">one-line =
docstring</a> example.<o:p></o:p></span></p><p class=3DMsoNormal><span =
style=3D'font-size:12.0pt'><o:p> </o:p></span></p><p =
class=3DMsoNormal><span style=3D'font-size:12.0pt'>The Notes say (fourth =
bullet):<o:p></o:p></span></p><p class=3DMsoNormal><span =
style=3D'font-size:12.0pt;color:#444444;background:#F9F9F9'>The =
docstring is a phrase ending in a period. It prescribes the function or =
method's effect as a command ("Do this", "Return =
that"), not as a description; e.g. <span =
style=3D'background:yellow;mso-highlight:yellow'>don't write =
"Returns the pathname ...</span>".<o:p></o:p></span></p><p =
class=3DMsoNormal><span =
style=3D'font-size:12.0pt;color:#444444;background:#F9F9F9'><o:p> </=
o:p></span></p><p class=3DMsoNormal><span =
style=3D'font-size:12.0pt;color:#444444;background:#F9F9F9'>However the =
docstring example for kos_root() is: “””<span =
style=3D'background:yellow;mso-highlight:yellow'>Return the =
pathname</span> of the KOS root =
directory.”””<o:p></o:p></span></p><p =
class=3DMsoNormal><span =
style=3D'font-size:12.0pt;color:#444444;background:#F9F9F9'><o:p> </=
o:p></span></p><p class=3DMsoNormal><span =
style=3D'font-size:12.0pt;color:#444444;background:#F9F9F9'>I’ve =
highlighted the areas that seem to contradict each other. Perhaps =
the example should be updated to conform to the =
notes?<o:p></o:p></span></p><p class=3DMsoNormal><span =
style=3D'font-size:12.0pt;color:#444444;background:#F9F9F9'><o:p> </=
o:p></span></p><p class=3DMsoNormal><span =
style=3D'font-size:12.0pt;color:#444444;background:#F9F9F9'>Thanks,<o:p><=
/o:p></span></p><p class=3DMsoNormal><span =
style=3D'font-size:12.0pt;color:#444444;background:#F9F9F9'>Paul<o:p></o:=
p></span></p><p class=3DMsoNormal><span =
style=3D'font-size:12.0pt;color:#444444;background:#F9F9F9'><o:p> </=
o:p></span></p><p class=3DMsoNormal><span =
style=3D'font-size:12.0pt;color:#444444;background:#F9F9F9'><o:p> </=
o:p></span></p><p class=3DMsoNormal><span =
style=3D'font-size:12.0pt;color:#444444;background:#F9F9F9'><o:p> </=
o:p></span></p><p class=3DMsoNormal><span =
style=3D'font-size:12.0pt'><o:p> </o:p></span></p></div></body></htm=
l>
------=_NextPart_000_0001_01D6DE0C.31E01070--
--===============5646173726735225868==
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: inline
_______________________________________________
Doc-SIG maillist - [email protected]
https://mail.python.org/mailman/listinfo/doc-sig
--===============5646173726735225868==--