Comments (20)
__str__
, __repr__
, __eq__
, __len__
or standard and a docstring would just by a dummy repetive text.
Same for
@propery
def name(self):
"""Docstring here."""
@getter.setter
def name(self, value):
"""Dumb docstring as this will alwasy be a setter for name."""
I think that developers should spend time write meaningful docstring rather than add dumb docstring to please a tool.
from pydocstyle.
PEP 257 does not say explicitly what to do with magic methods. But is sais the follwoing:
Public methods (including the
__init__
constructor) should also have docstrings.
Which makes me think that methods like __str__
should also be documented (they are public after all).
2 open questions:
- Is my interpretation correct?
- Should we allow disabling this with some command-line flag?
from pydocstyle.
Is my interpretation correct?
I think so. All things considered, the magic methods work because they're technically public. No one will ever call: foo.__str__()
explicitly but the public API is clearly str(foo)
. With that said, those methods can be considered private or implementation details. That brings up a different question for me: Should this consist of a whitelist? Consider someone using __method__
to hide an implementation detail. In that case, we shouldn't tell them they have to document it. (So I guess I answered my own question, but I'm not sure everyone agrees with me.)
from pydocstyle.
I think the correct interpretation of PEP257 is irrelevant. We should allow
to enforce what the user prefers.
If a user would add pep257.py to a build script or commit hook and expect
it to pass (i.e., you can't ignore errors), it should be possible to
configure the tool in the maximum possible granularity, otherwise no one
would use it.
On Dec 26, 2013 4:15 AM, "Ian Cordasco" [email protected] wrote:
Is my interpretation correct?
I think so. All things considered, the magic methods work because they're
technically public. No one will ever call: foo.str() explicitly but
the public API is clearly str(foo). With that said, those methods can be
considered private or implementation details. That brings up a different
question for me: Should this consist of a whitelist? Consider someone using
method to hide an implementation detail. In that case, we shouldn't
tell them they have to document it. (So I guess I answered my own question,
but I'm not sure everyone agrees with me.)β
Reply to this email directly or view it on GitHubhttps://github.com//issues/60#issuecomment-31209038
.
from pydocstyle.
I think the correct interpretation of PEP257 is irrelevant.
No, the correct interpretation of PEP 257 should be the default behavior.
We should allow to enforce what the user prefers.
Agree. This should be done through command-line flags, etc.
from pydocstyle.
I agree.
On Dec 26, 2013 12:33 PM, "Vladimir Keleshev" [email protected]
wrote:
I think the correct interpretation of PEP257 is irrelevant.
No, the correct interpretation of PEP 257 should be the default behavior.
We should allow to enforce what the user prefers.
Agree. This should be done through command-line flags, etc.
β
Reply to this email directly or view it on GitHubhttps://github.com//issues/60#issuecomment-31217404
.
from pydocstyle.
I agree that magic methods donβt need docstrings (the language defines their interface and role), with a possible exception of init. I tend to document constructors in the class docstring, but sometimes it makes more sense to add a docstring to init.
from pydocstyle.
I agree with @merwok and @adiroiban. The behavior of most magic methods should be completely obvious based on the rest of the class, but __init__
is necessarily specific to the class and its docstring should explain the purpose of the constructor's arguments.
from pydocstyle.
And so...? Is now possible disable this with a command-flag or nah?
from pydocstyle.
Not as of now.
On Oct 17, 2014 3:26 AM, "Matheus" [email protected] wrote:
And so...? Is now possible disable this with a command-flag or nah?
β
Reply to this email directly or view it on GitHub
#60 (comment).
from pydocstyle.
I was thinking about how to implement this. If possible, I would like all customization for errors to happen by ignoring and selecting errors, so naturally I would like to have a new error code for magic methods
However, there is the issue of the exceptions that probably should be documented. We talked about __init__
, but there maybe some others in that group - e.g., __call__
.
Some questions:
- should the new error code exclude these "special" magic methods?
- Is it clear which magic methods are "special" in this way?
from pydocstyle.
Is it clear which magic methods are "special" in this way?
I would say any magic method that takes a variable number of arguments should be documented. The arguments to (and behavior of) methods like __str__
, __add__
, __setattr__
, etc. are well-defined in the data model: https://docs.python.org/3/reference/datamodel.html
from pydocstyle.
From what I see, the only magic methods with a variable number of arguments are __init__
, __new__
and __call__
. So I'm currently leaning towards creating a new "missing docstring in magic method" error that excludes just these three methods. Any objections?
from pydocstyle.
See a summary of magic methods here: http://www.rafekettler.com/magicmethods.html#appendix1
from pydocstyle.
π
from pydocstyle.
I'm running the latest release (1.0), which it looks like this landed in, but I'm finding I have to explicitly pass --add-ignore=D105
to suppress complaints about missing docstrings in my __str__
methods. It looks like the intention of this issue was to suppress these by default. Did I miss something or misinterpret?
from pydocstyle.
@jab The new error is not suppressed by default. It exists so that you could suppress it, if you want to.
from pydocstyle.
@Nurdok Did you mean not suppressed by default?
from pydocstyle.
@jab yes, edited.
from pydocstyle.
Thanks for clarifying.
from pydocstyle.
Related Issues (20)
- option to ban `noqa` comments that don't specify a code
- D102 - false positive on overload with comment
- cosmetic bug: wrong version stamp in webpage title: 1.0.0 instead of 2.1.1
- The match-dir parameter is not used. HOT 4
- Not detecting wrong DocStrings HOT 1
- Your website is down - https://pydocstyle.org HOT 3
- Crash with simple f-string HOT 7
- Docs website is down? HOT 1
- sdist: PKG-INFO should list LICENSE-MIT in License-File
- `D300` and `D301` false positives on docstrings with escaped triple quotes in them
- Should `__main__.py` really be considered a public module?
- Option to not report error for empty file HOT 1
- test_simple_fstring and test_fstring_with_args fail with Python 3.12 beta HOT 2
- 6.3.0: incorrect version in pyproject.toml?π€ HOT 2
- pydocstyle 6.3.0 fails silently on a python script that has no .py extension
- Rule for missing PEP 698 `@overrides` decorators?
- Keyword Args not recognized in Google convention with no return
- Python3.12: Two tests fail HOT 1
- Google convention section names not properly checked
- D417 not raised in a standard Google configuration with missing arguments descriptions
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
π Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. πππ
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google β€οΈ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from pydocstyle.