As a docstring I don't find this superior. Docstrings (for me) are usually viewed as quick little pop-up boxes in my editor. The existing clojure docstring for `apply` gives me the information I need much faster and with less screen real estate. YMMV.
On Monday, September 25, 2017 at 9:42:12 AM UTC-7, Phillip Lord wrote: > > > > 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....@gmail.com <javascript:>> 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...@gmail.com > <javascript:>> > > 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.
