Re: Some docs on comparators, including mistakes to avoid, & Clojure "extended doc strings"
A document that may perhaps contain more than most people want to know about Clojure = and == https://github.com/jafingerhut/thalia/blob/master/doc/other-topics/equality.md Andy On Thu, Apr 4, 2013 at 12:49 PM, Andy Fingerhut wrote: > 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. > -- -- 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.
Re: Some docs on comparators, including mistakes to avoid, & Clojure "extended doc strings"
This seems like a good fit for http://clojure-doc.org/ -- -- 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.
Re: Some docs on comparators, including mistakes to avoid, & Clojure "extended doc strings"
Thumbs up on the comparators doc! On Apr 4, 2013 12:49 PM, "Andy Fingerhut" 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.
Some docs on comparators, including mistakes to avoid, & Clojure "extended doc strings"
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.
