Comments (17)
I think this issue should be reopened as #235 does not seem to affect the general case where a method decorated with @property
is requried to be in imperative mood. So while Alias
might be treated as a potential imperative now, properties are still not allowed a docstring starting with words like The
or A
.
from pydocstyle.
I have found this rule useful, but perhaps it should not apply to properties. All other method docstrings should be imperative (and I can't really think of any false positives), but property docstrings are typically not going to be imperative unless you do something like "Get the value of...".
from pydocstyle.
A whitelist would be unmaintainable in my opinion @jacebrowning
from pydocstyle.
Large neural network language models such as GPT-3 open up completely new possibilities to check if a sentence is in imperative mode. Maybe this should be added to this project.
I don think this would impair productivity even more than attempting to check if docstrings are in imperative to begin with.
@bjrne
from pydocstyle.
I'd also support reopening this. Imperative mood checking is a very promising feature but enforcing it for @property
"functions" forces me to ignore all D401
errors.
from pydocstyle.
I found another good example of a false positive: """Focus the application."""
Perhaps pep257
could have a list of acceptable words that end in s?
from pydocstyle.
You donโt write docstring for them :)
from pydocstyle.
Actually, this might read better as """An alias for consistency with the rest of pocketlint."""
from pydocstyle.
It could be interesting to investigate using NLTK (http://www.nltk.org/) here, although that would almost certainly be massive overkill.
from pydocstyle.
I asked about this in English StackExchange: http://english.stackexchange.com/questions/216043/telling-if-a-word-is-a-verb-in-the-imperative-mood
from pydocstyle.
This could be fixed by listing imperative forms of verbs and comparing with, say, a Porter stemmer (assuming English).
If the stemmed form of the word is in the stemmed list of verbs, then it's probably a verb. But if the unstemmed form is not in the unstemmed list, it's not in the imperative form.
This would have a much lower false positive rate than the current heuristic, but a somewhat larger false negative rate, depending on the size of the word list. But I'm guessing that relatively small lists of verbs would cover a high percentage of docstrings, due to the constrained nature of the language used (outside of domain-specific jargon).
We could generate a reasonably good word list by scanning docstrings of a few largish Python projects and manually removing words that are not imperative verbs.
from pydocstyle.
Also it's out of scope to do a full grammar analysis, so we could never detect imperative or not in a docstring like
def median(xs):
"""Given a list of numbers xs, return the median."""
We could only flag up words that are verbs but not in an imperative form.
from pydocstyle.
I started scanning my codebase for the verbs we use here. We could also add a blacklist approach - there are words that are very much indicators of non-imperative docstrings.
from pydocstyle.
Can this issue be closed, now #235 is merged?
from pydocstyle.
I would too. Or at least allow "The" or "A" for them.
from pydocstyle.
Please open a new issue if you think D401 should not apply to @property
functions*. That is not the issue that was addressed here.
* But I would argue it should because if you allow a noun phrase for the getter what do you write in the docstring for a setter or a deleter?
from pydocstyle.
I've started a new thread: #566.
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.