Comments (9)
Either I care whether it's implemented as a generator or return statement, and I should use the
Generator[...]
type hintOr I don't care about it, and I should probably use the more generic
Returns
section in the docstring since there is no guarantee that the concrete implementation will actually yield something.
That's exactly what I was thinking.
from pydoclint.
Thank you both for sharing useful feedback!
With the discussions above, I'm going to close this issue as "fixed". Please feel free to reopen it if any additional fixing is necessary.
from pydoclint.
I also do not understand with DOC201 is triggered in this case.
Pydoclint wants you to document that the method returns an Iterator which is different from yielding values which makes the method return a Generator. This is linked to #15.
from pydoclint.
I also do not understand with DOC201 is triggered in this case.
Pydoclint wants you to document that the method returns an Iterator which is different from yielding values which makes the method return a Generator. This is linked to #15.
Thanks! So I guess that's one more edge-case for DOC201 😉 The rule would be something like if a method is abstract and its output is either Iterable/Iterator/Generator and it contains a yield section, then DOC201 doesn't apply?
from pydoclint.
But why would you want to have a yield section but not a Generator return type?
from pydoclint.
For exactly the same reason as mentioned there: #15 (comment)
There is no reason that this combination of signature/docstring would work for a concrete method, but not for an abstract method?
from pydoclint.
Hi @ghjklw:
Thank you for raising this issue. This is indeed an edge case that I didn't think of.
Let me explain the "strange" behavior between your Example 1 and Example 2.
In Example 1, pydoclint raises DOC201 and DOC403 because: it sees a Yields
section in the docstring, so it's expecting a yield
statement in the method body, not in the method signature.
This is because: when we see -> Iterator[something]
in the signature, we can't be sure that the method is yielding stuff or returning stuff -- see my example here (#15 (comment)). Therefore, the yield
statement in the method body is our only clue.
The situation is different for Example 2, where there is -> str
in the signature. Since the return type annotation is not Iterator[...]
, we are certain that this method should return stuff rather than yield stuff.
That's why I wrote (hasReturnStmt or hasReturnAnno)
in the code:
pydoclint/pydoclint/visitor.py
Lines 449 to 450 in 31e6a0b
So I actually don't know what the best solution should be: are we OK that both -> Iterator[...]
and -> Generator[...]
in abstract methods can correspond to a Yields
section in the docstring? (If we are OK with this, this example will fall through the cracks.)
from pydoclint.
Hi @ghjklw :
I merged PR #35. Please feel free to take a look at the code change, if you are curious.
Please note that your 1st example will still trigger violations, because if the return type annotation is Iterator[...]
, the linter still expects a return section, rather than a yield section.
If you have better suggestions on how the linter should handle Iterator/Generator and yields, please feel free to share them!
from pydoclint.
Thanks! I think that's a good compromise. Thinking again about this example I think @real-yfprojects has a point regarding the use of Iterator[...]
in an abstract class or protocol:
- Either I care whether it's implemented as a generator or return statement, and I should use the
Generator[...]
type hint - Or I don't care about it, and I should probably use the more generic
Returns
section in the docstring since there is no guarantee that the concrete implementation will actually yield something.
By the way, thanks for all the work you're doing ! It's fantastic to have such a tool 😃 I only hope I had the skills to build a VS Code extension for it 😄 !
from pydoclint.
Related Issues (20)
- Request: not throwing DOC501 for `abstractmethod` HOT 2
- Docs request: `pre-commit` config for `flake8` HOT 1
- Parameters not processed correctly for numpy style with incorrect underscoring HOT 1
- Add shortcuts for long typing.Annotated type hints HOT 3
- BUG: Return literal with double quotes incorrectly raises v203 HOT 3
- Request: Add configuration option that allows for type hint in signature _or_ docstring, but not both HOT 2
- **kwargs only arguments throw DOC106 and DOC109 HOT 2
- Failure to detect the `import typing as tt` convention HOT 2
- Failure to detect `noqa` statement HOT 5
- Google style: Allow omitting only the `Returns`/`Yields` if summary starts with `Return(s)/Yield(s)` HOT 16
- Google style: Allow documenting `@property`s as a member HOT 5
- Allow more control over`--skip-checking-short-docstrings` HOT 4
- More config control for type hinting in signature HOT 2
- Option to only check for non-existent params in pydocs, rather than params missing in pydocs HOT 2
- Deprecated command line argument `--src` leads to errors or missing proper documentation HOT 2
- Google style: Allow omitting `*args` and `**kwargs` from doc string HOT 3
- Add class attributes checking support HOT 1
- False positive DOC201 HOT 1
- False positive DOC405 HOT 2
- False positive 403 with "yield from" statement
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 pydoclint.