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 [email protected] Note that posts from new members are moderated - please be patient with your first post. To unsubscribe from this group, send email to [email protected] 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 [email protected]. For more options, visit https://groups.google.com/groups/opt_out.
