Worth pointng out: if you know exactly how to use a function, how much of an actual problem is that the docstring is contrived?
I'd sure like nicer docstrings, but also I understand that the authors (core and community alike) have limited bandwidth.
So we may never see a "100% solution", which is perfectly fine.
(Thought exercise: say the docstrings get just a little nicer. Couldn't that create even more problems in some ways? Now everyone expects nice docstrings, and bikesheds about format, contents, etc)
The issue with understanding how to use a function and having difficulty with the docstring is:
I assume my knowledge is fallible, and that the docstring is the de facto source of information for that function.
If my knowledge clashes with what I understand the docstring to convey, then my understanding vanishes. I go from happily coding to "Uh, I don't know what I'm doing" in seconds.
It's not a super frequent issue, and I've reported it when it is, but I've heard many other people express similar sentiments. It's a slow process to improve this because everyone understands written language slightly differently.
Worth pointng out: if you know exactly how to use a function, how much of an actual problem is that the docstring is contrived?
I'd sure like nicer docstrings, but also I understand that the authors (core and community alike) have limited bandwidth.
So we may never see a "100% solution", which is perfectly fine.
(Thought exercise: say the docstrings get just a little nicer. Couldn't that create even more problems in some ways? Now everyone expects nice docstrings, and bikesheds about format, contents, etc)