I wasn't sure where to post this, maybe a mailing list?
PEP-257: String literals occurring immediately after a simple
assignment at the top level of a module, class, or __init__ method are
called "attribute docstrings".
```python
class Foo:
attr = 1
"""PEP for doscstrings on attrs is that it comes after. So this
is for 'attr'"""
some_other_attr = 'is this the one we're documenting?'
```
A semicolon is a natural delimiter for single-line attribute docstrings.
```python
class Foo:
# pylint: disable=multiple-statements
attr = 1; """PEP for doscstrings on attrs is that it comes after.
So this is for 'attr'"""
some_other_attr = 'is this the one we're documenting?'
```
The PEP style is obviously unclear. Docstrings, in general, are hard
to format well... the simplest rule is that they must be visually
linked to the thing they are documenting. Fortunately, the semicolon
allows us to visually connect a single-line docstring to its attribute
-as long as the line-length is short.
As an alternative a comment or something could provide visual cues,
and if this is the standard, it should be added to the PEP on
docstrings.
```python
class Foo:
attr = 1;
"""PEP for doscstrings on attrs is that it comes after. So this is
for 'attr'"""
# -----
some_other_attr = 'is this the one we're documenting?'
```
_______________________________________________
Doc-SIG maillist - Doc-SIG@python.org
https://mail.python.org/mailman/listinfo/doc-sig
