ClojureDocs currently show just the original docstring followed by user-contributed examples. I think a lot of readers would benefit from somethig like this:
apply (apply f args* argseq) *Scripture:* Applies fn f to the argument list formed by prepending args to argseq. *Interpretation: *The first argument (f) is a function and the last argument is a sequence (argseq). Calls f with elements of argseq as its arguments. If more arguments are specified (args*), they are added to the beginning of the argseq to form the complete argument list with which f is called. * * *Examples:* (as usual) -marko On Wednesday, March 27, 2013 11:33:04 AM UTC+1, Marko Topolnik wrote: > > Now that Michael mentioned it, the docstring of *apply* says > > Applies fn f to the argument list formed by prepending intervening >> arguments to args. > > > I challenge any Clojure newbie to decipher this Hickeyism for me. This is > of course no exception; most of clojure.core is like that. > > I can personally testify to having learned (and *had to* learn) much more > from source code than from docstrings. M-. has always been my best > friend; C-d C-d came merely as a hint from Rich while solving the > "compile me in your head" puzzle. > > -marko > > On Wednesday, March 27, 2013 11:17:05 AM UTC+1, Ryan wrote: >> >> The idea that people should read the source to get reasonably >>> straightforward stuff done is wrong and does a lot of long term damage to >>> the community. >> >> >> I believe Jim meant to check the source to figure out how does it work, >> not that the way it's implemented is the most proper way to implement it. >> If that's not what you wanted to point out can you please explain? >> >> On Wednesday, March 27, 2013 5:13:35 AM UTC+2, Michael Klishin wrote: >>> >>> >>> 2013/3/27 Jim - FooBar(); <jimpi...@gmail.com> >>> >>>> aaa see? always check the docs first and the sources second (if >>>> available)...I should have done that as well :) >>> >>> >>> Definitely don't just check the sources and think it's something normal. >>> >>> Complain loudly to maintainers on this list that their documentation has >>> gaps and they should >>> clarify this and that. The idea that people should read the source to >>> get reasonably straightforward >>> stuff done is wrong and does a lot of long term damage to the community. >>> -- >>> MK >>> >>> http://github.com/michaelklishin >>> http://twitter.com/michaelklishin >>> >> -- -- You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com Note that posts from new members are moderated - please be patient with your first post. To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en --- You received this message because you are subscribed to the Google Groups "Clojure" group. To unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/groups/opt_out.
