The repeated message from the authors is that clojure.core docstrings are not gonna improve.
If you think it's an easy problem to solve, please point out a single resource (library, website) which is 100% high-quality, comprehensive, up-to-date, IDE-integrated, and noncontroversial. Where is it? Why haven't we all adopted it?
The facts are: we have good-enough docs, nREPL, a massive corpus of beginner material (books, videos) and real-time support from enthusiasts on Slack.
If you ain't clojuring, it's because you don't want to!
I don't think that anyone believes that it's an easy problem to solve, but it IS a problem.
I've been Clojuring since 1.0, contributed 100s of examples to Clojure docs websites, and I still don't understand some of the .core docstrings even when I know exactly how to use the function.
It may not be easy to solve, but it does need to be solved.
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.
I'd like to highlight an issue with the docstrings as they stand. It has been stated by Rich himself on Jira that he doesn't like or want usage examples in docstrings. However, it would seem that many other people would love to see exactly that; myself included.
He made this clear a few years ago - I don't know if he has changed his mind since?
This would probably help beginners more than anybody else.
docstrings are intended to be a concise statement of what the function does and we would like to stick with that.
Examples are also great. We would love to have documentation pages (or even doc functions in the repl) that combine multiple sources of information to help you out (docstrings, examples, see alsos, etc). That stuff does not have to be "in the docstring" for it to be available to you as a user.
For example, clojuredocs.org does exactly this, combining multiple sources of information into one combined page (ex: http://clojuredocs.org/clojure.core/zipmap). There used to be an api for clojuredocs.org and a repl lib you could use that would give you an additional function to get those examples at the repl too (I think that fell out of maintenance).
The summary is, we can both have docstrings that don't include examples AND provide examples by merging docstrings with other things for the user.
I think the Java standard library docs fall in this category. It's always been one of my favorite part of working with the language.
(I guess the library design is controversial, or rather, it is now... Collections are looking rather outdated just to cite the obvious. But as for the documentation, it's still killer.)
I believe the reason, besides the fact that docstrings can be consumed via a REPL, is that the docstrings get compiled into the final classes. So if we had huge JavaDoc style docstrings, it would negatively affect loading times.
If you think it's an easy problem to solve, please point out a single resource (library, website) which is 100% high-quality, comprehensive, up-to-date, IDE-integrated, and noncontroversial. Where is it? Why haven't we all adopted it?
The facts are: we have good-enough docs, nREPL, a massive corpus of beginner material (books, videos) and real-time support from enthusiasts on Slack.
If you ain't clojuring, it's because you don't want to!