4 ms·
Kudos for all the contributions! Worth pointng out: if you know exactly how to use a function, how much of an actual problem is that the docstring is contrived
by vemv 8y ago
Kudos for all the contributions!
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)
- casion 8y agoThe 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. Still... it does need to continue improving.