If the docstring were more structured (either using conventions within the docstring, or additional metadata elements on the var), then this would not be a problem. First line for tooltip, main doc for hover-over, examples on request, that kind of thing.
Phil Beau Fabry <imf...@gmail.com> writes: > 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. >> -- Phillip Lord, Phone: +44 (0) 191 208 7827 Biology, Medicine, Computing Email: phillip.l...@newcastle.ac.uk School of Computing, http://homepages.cs.ncl.ac.uk/phillip.lord Room 5.012 Urban Sciences Building, skype: russet_apples Newcastle University, twitter: phillord NE4 5TG -- 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.
