Thumbs up on the comparators doc! On Apr 4, 2013 12:49 PM, "Andy Fingerhut" <andy.finger...@gmail.com> wrote:
> I am seriously considering the idea of working on some "extended doc > strings" for Clojure functions. Having only scratched the surface so far, > I have learned that it could take a *lot* of hours to write such > documentation for every function distributed as part of Clojure, at least > if written in the way I've done so far for compare, sort, and for > comparator functions. > > The document on comparator functions alone might be of interest to a few > people. You can read it here: > > > https://github.com/jafingerhut/thalia/blob/master/doc/other-topics/comparators.md > > It has a few examples of good comparators, and mistakes to avoid when > writing them that I have seen asked about here. I take some inspiration > from what I consider to be pretty good documentation for a programming > language: Perl. Type "man perlfunc" in a Linux or Mac OS X shell and > you'll see what I mean. Useful examples, corner cases, pitfalls, etc. I > like, use, and promote ClojureDocs.org, but I also like the idea of > something a bit more curated. > > I don't have any code yet where you can type an expression in a REPL and > get these docs back, but that wouldn't be hard to do. It wouldn't be very > useful to implement that until there are a lot more extended doc strings > written. I'll announce more later if that happens. I know Rich Morin > expressed some interest in a project like this in an earlier thread [1], > but if anyone is interested, feel free to contact me privately and we can > talk. > > [1] > https://mail.google.com/mail/?shva=1#search/label%3Aclojure+rich+morin/13c5fab22e24cd23 > > I do have a skeleton of a directory tree with regular predictable names > for Markdown-format files for every public symbol in Clojure 1.5.1 (not all > checked in to that Github repo yet), using Lee Hinman's lein-clojuredocs to > extract that info from it and all other Clojure contrib libraries. > > > Side note: At the end my comparators document has the beginnings of a > "compare any pair of values" comparator mentioned by Mark Engelberg as a > wish list item in a message from last November [2]. That version, called > cc-cmp, still doesn't work for Clojure sets and maps, but it wouldn't be > difficult to extend it to those by sorting the elements/keys and then > comparing them as sequences. I suspect it would be best to write a version > using multimethods or protocols that could be easily extended by others to > additional types, without needing to modify the original code. > > [2] > https://mail.google.com/mail/?shva=1#search/engelberg+compare/13b1e8a3f7f9a59d > > Andy > > -- > -- > 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. > > > -- -- 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.
