[prev in list] [next in list] [prev in thread] [next in thread] 

List:       python-ideas
Subject:    [Python-ideas] =?utf-8?q?Re=3A_Runtime-accessible_attribute_docstrings_=E2=80=93_take_2?=
From:       Ricky Teachey <ricky () teachey ! org>
Date:       2021-12-15 4:27:34
Message-ID: CAP0nE65ih7W36WVohyRWT63SPWiTNrvS8wBAET5+tz70L+Wh7A () mail ! gmail ! com
[Download RAW message or body]

[Attachment #2 (multipart/alternative)]


On Tue, Dec 14, 2021, 9:49 PM Paul Bryan <pbryan@anode.ca> wrote:

> Interesting. Some apparent downsides:
>
> - doesn't apply to class attributes
> - objects with `__slots__` can't dynamically add attributes
>

Also doesn't apply to module level members.

To my mind these are significant downsides. And it also represents yet
another way people are documenting attributes in the wild.

Here's another I learned if which is supported by sphinx autodoc:

comment tag colon docstring
attribute statement

Example:

#: spam
x = 1

Using this style, the documentation has to come before the attribute.

Obviously- unless VERY big change is introduced- this "docstring" will
never be runtime accessible since it's a comment. But it does represent yet
another way people are doing documentation in the wild.

Sigh.

Rick.

[Attachment #5 (text/html)]

<div dir="auto"><div><br><br><div class="gmail_quote"><div dir="ltr" \
class="gmail_attr">On Tue, Dec 14, 2021, 9:49 PM Paul Bryan &lt;<a \
href="mailto:pbryan@anode.ca">pbryan@anode.ca</a>&gt; wrote:<br></div><blockquote \
class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc \
solid;padding-left:1ex"><div><div>Interesting. Some apparent \
downsides:</div><div><br></div><div>- doesn&#39;t apply to class \
attributes</div><div>- objects with `__slots__` can&#39;t dynamically add attributes  \
</div></div></blockquote></div></div><div dir="auto"><br></div><div dir="auto">Also \
doesn&#39;t apply to module level members.  </div><div dir="auto"><br></div><div \
dir="auto">To my mind these are significant downsides. And it also represents yet \
another way people are documenting attributes in the wild.</div><div \
dir="auto"><br></div><div dir="auto">Here&#39;s another I learned if which is \
supported by sphinx autodoc:</div><div dir="auto"><br></div><div dir="auto">comment \
tag colon docstring</div><div dir="auto">attribute statement</div><div \
dir="auto"><br></div><div dir="auto">Example:</div><div dir="auto"><br></div><div \
dir="auto">#: spam</div><div dir="auto">x = 1</div><div dir="auto"><br></div><div \
dir="auto">Using this style, the documentation has to come before the \
attribute.</div><div dir="auto"><br></div><div dir="auto">Obviously- unless VERY big \
change is introduced- this &quot;docstring&quot; will never be runtime accessible \
since it&#39;s a comment. But it does represent yet another way people are doing \
documentation in the wild.</div><div dir="auto"><br></div><div \
dir="auto">Sigh.</div><div dir="auto"><br></div><div dir="auto">Rick.</div><div \
dir="auto"><br></div></div>



_______________________________________________
Python-ideas mailing list -- python-ideas@python.org
To unsubscribe send an email to python-ideas-leave@python.org
https://mail.python.org/mailman3/lists/python-ideas.python.org/
Message archived at https://mail.python.org/archives/list/python-ideas@python.org/message/NTYRIIDYNJUUKT4PCVJEHOBFQDOQ32JP/
 Code of Conduct: http://python.org/psf/codeofconduct/



[prev in list] [next in list] [prev in thread] [next in thread]