3 ms·

Have you filed CLJ jira tickets about those docstrings? If not, then we are not able to hear your concerns. We fix and improve a bunch of docstrings in every re

Have you filed CLJ jira tickets about those docstrings? If not, then we are not able to hear your concerns. We fix and improve a bunch of docstrings in every release: https://dev.clojure.org/jira/secure/IssueNavigator.jspa?reset=true&jqlQuery=project%3DCLJ+and+status%3DClosed+and+approval%3DOk+and+labels%3Ddocstring+order+by+fixVersion+desc https://dev.clojure.org/jira/secure/IssueNavigator.jspa?rese... Have you filed documentation issues on the Clojure web site? If not, we don't know what needs to be improved. We have closed 100s of PRs and issues on the site in the last couple years: https://github.com/clojure/clojure-site/issues?utf8=%E2%9C%93&q=is%3Aclosed https://github.com/clojure/clojure-site/issues?utf8=%E2%9C%9...

casion 8y ago
Yes, I have done both. Thank you for your tireless work on improving Clojure and the surrounding ecosystem.
- puredanger 8y ago
  Thanks!
mr_custard 8y ago
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.
- puredanger 8y ago
  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.
  - mr_custard 8y ago
    Thanks for explaining the rationale, as well as future hopes and plans for documentation.

casion 8y ago

Yes, I have done both. Thank you for your tireless work on improving Clojure and the surrounding ecosystem.

puredanger 8y ago
Thanks!

mr_custard 8y ago

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.

puredanger 8y ago
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.
- mr_custard 8y ago
  Thanks for explaining the rationale, as well as future hopes and plans for documentation.