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 hav

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