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.
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.
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.