Set up system of code examples and details for message documentation #5934
Conversation
Pull Request Test Coverage Report for Build 2008171386
💛 - Coveralls |
doc/exts/pylint_messages.py
Outdated
| PYLINT_MESSAGES_PATH = PYLINT_BASE_PATH / "doc" / "messages" | ||
| """Path to the messages documentation folder.""" | ||
|
|
||
| PYLINT_MESSAGES_DATA_PATH = PYLINT_BASE_PATH / "doc" / "data" / "messages" | ||
| """Path to the messages documentation folder.""" |
There was a problem hiding this comment.
Can we distinguish these two docstrings?
There was a problem hiding this comment.
Oops, that's a mistake. Fixing!
| def foo(): | ||
| """A dummy description.""" |
There was a problem hiding this comment.
| def foo(): | |
| """A dummy description.""" | |
| def add(a: Any, b: Any) -> Any: | |
| """Add a and b.""" | |
| return a + b |
There was a problem hiding this comment.
I mean, what does adding Any really provide here? Without any information mypy and others will already infer everything as Any.
| def foo(): | ||
| pass # [emtpy-docstring] |
There was a problem hiding this comment.
Not related to the actual MR, but I think code example could be 'real' and 'exciting' with animal, vegetal and real concepts or code example to be more rememberable. Also typing by default would influence begginner to use it later.
| def foo(): | |
| pass # [emtpy-docstring] | |
| def add(a: Any, b: Any) -> Any: | |
| return a + b # [emtpy-docstring] |
Foos and bars are traditional and have the benefit of not introducing more concept than the message itself, but also a little boring and I think human learn better with (fun) examples than with generic examples.
There was a problem hiding this comment.
Hm, in this case it doesn't really hurt, but I actually think the examples should be as bare bones as possible. That helps to identify the actual issue.
To make a (bad) example from this case: is empty-docstring raise for all functions or only for functions with parameters? In this case it doesn't really matter because that though is nonsensical, but I think there are messages where it actually helps if the example is as simple as possible.
There was a problem hiding this comment.
You're right about "any", maybe we could another example ? (def do_nothing() -> None:).
There was a problem hiding this comment.
I think you're also right about barebone being a good thing, but I dislike foo/bar for documentation. For a beginner the first thing they have to do is to read https://en.wikipedia.org/wiki/Foobar and learn about our little software programmer internal meme. We can probably make barebone examples that school children would understand without prior knowledge.
There was a problem hiding this comment.
Ah shit, I completely forgot about this.
I'll keep it in mind for future PRs 👍
There was a problem hiding this comment.
Don't worry we'll have to review hundred of examples that were in pylint-error, there's no use nitpicking about the style right now 😄
| async def foo(): | ||
| def _inner_foo(): | ||
| yield from [1, 2, 3] | ||
|
|
||
|
|
||
| async def foo(): | ||
| yield 42 |
There was a problem hiding this comment.
| async def foo(): | |
| def _inner_foo(): | |
| yield from [1, 2, 3] | |
| async def foo(): | |
| yield 42 | |
| async def count_to_three() -> Iterator[int]: | |
| def _inner_count_to_three() -> Iterator[int]: | |
| yield from [1, 2, 3] | |
| async def the_answer() -> Iterator[int]: | |
| yield 42 |
| async def foo(): | ||
| yield from [1, 2, 3] # [yield-inside-async-function] |
There was a problem hiding this comment.
| async def foo(): | |
| yield from [1, 2, 3] # [yield-inside-async-function] | |
| async def count_to_three() -> Iterator[int]: | |
| yield from [1, 2, 3] # [yield-inside-async-function] |
CONTRIBUTORS.txtif you are a new contributor.Type of Changes
Description
This closes #5527. I'd like to create a separate issue to track the progress of migrating the code examples of
pylint-errors.This allows for each message to have a
good.py,bad.py,related.rstanddetails.rstsection. I have added two examples which can be viewed here and here. Based on this and this. Note that the original example is actually incorrect.The
bad.pyis written in the same style as the functional test so that at one point we could test against them. For now, I have considered that out of scope. (I also want to find a way to not do that every PR as not to inflate test time).I think the structure works but let me know what you think!