Clojure's doc strings, though, contain knowledge that is not clear. Consider, this documentation:
Returns a new seq where x is the first element and seq is the rest. x is the name of a parameter. So is the the second occurence of seq, but not the first. Neither first, nor rest refer to the functions in clojure.core, although both probably should do. Compare this to the documentation for "apply" from Andy Fingerhuts thalia. `f` is a function and the last argument `args` is a sequence. Calls `f` with the elements of `args` as its arguments. If more arguments `x`, `y`, etc. are specified, they are added to the beginning of `args` to form the complete argument list with which `f` is called. Examples: ```clojure\nuser=> (apply + [1 2]) ; same as (+ 1 2) 3 user=> (apply + 1 2 [3 4 5 6]) ; same as (+ 1 2 3 4 5 6) Which is essentially superior in every way. The existence of neither specs nor clojure.org don't really change this. It would be possible to go even further than this; consider the runnable doc strings of rust -- the examples are also tests. Emacs' dash.el does the same thing. Still, it's been this way since I first started using clojure (1.3/1.4) so I suspect that it's not going to change. Phil Stuart Halloway <stuart.hallo...@gmail.com> writes: > Clojure has great data, and great metadata. Documentation strings are *not* > great data, they are strings. > > If you want to provide more structured support than docstrings to help > someone use Clojure, look at specs for inspiration. They are made of data, > and they live in a registry separate from Clojure's var system. This kind > of decoupling supports composition and tooling without requiring any > addition or change to Clojure. > > I would also echo Matching Socks: Having more and better guides at > clojure.org would be great. The contribution process is described at > https://github.com/clojure/clojure-site/blob/master/content/community/contributing_site.adoc > . > > Regards, > Stu > > On Mon, Sep 11, 2017 at 5:23 AM, Matching Socks <phill.w...@gmail.com> > wrote: > >> I am not convinced I would have found the API docs on reducers or zippers >> more informative if all references had been tidily markdown'ed. >> >> The new clojure.org welcomes contributions of topical overviews. That's >> helpful. >> >> But, to interpret docstrings, nothing helps like perspective. The thing >> about perspective is that there could be so many. I like "Clojure >> Programming" by Emerick, Carper & Grand. -- 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/d/optout.
