On Tue, Jan 20, 2009 at 10:09 AM, Mark Addleman <mark_addle...@bigfoot.com> wrote: > > I'm a long time Java programmer and, before that, a Smalltalker. One > of the major biggest challenges I face when picking up a new language > is getting a working understanding of its libraries. I believe that > standardizing on a doc format was a pretty important driver for Java's > success. > > As I see it, Java has three natural forms that aid a newbie learning > its libraries: Packages, hierarchies and type declarations. Packages > and hierarchies give newbies a few good ways of browsing the libraries > to gain familiarity and, much more importantly, a way of organizing > all those bits of information in our heads. Type declarations serve > as a good way of documenting the parameters for methods (e.g. > parameter one must respond to well-defined set of messages). > > I'm willing to forgo the documentation benefits of type declarations > to get back to dynamic typing that I enjoyed with Smalltalk but I'm > too old to try to read through, memorize and create memes for a new > library as rich as Clojure's. At the same time, I think there are > enough limitations to JavaDoc to warrant spending a little time trying > to come up with a better alternative. > > I haven't thought my proposal through very well, but here's the idea: > a multidimensional relational, categorization system similar to the > tagging system seen on blogs or the WikiBadge (http://c2.com/cgi/wiki? > WikiBadge) system. The idea goes something like this: Clojure > functions could be tagged with any user created tag. Tags can be > related to one another through named relations to provide context. > For example: > > Tags: "java interop" "primitive" "array function" > Relations: "is a" > > A little prolog-ese: > is_a(primitive, java_interop) > is_a(array_function, primitive) > array_function(areduce) > > With the appropriate logic, a search for "is_a(?, java_interop)" would > yield "areduce" > > I suspect that by applying tags to function arguments and with careful > definition of relations, a Clojure IDE could perform similarly fancy > suggestions and refactorings as modern Java IDEs. > > I'm throwing this out to the group in an effort to jump start some > real documentation efforts. It would be a tremendous boon to > Clojure's up-take, I think.
I completely agree that some form of categorization of core Clojure functions would be very helpful. For example, which of the hundreds of core functions perform some operation on a string? I started trying to categorize them for my own benefit. See the first table at http://www.ociweb.com/mark/programming/Clojure.html. This isn't yet complete. Stuart H., I think something like this would make a great appendix in your book! -- R. Mark Volkmann Object Computing, Inc. --~--~---------~--~----~------------~-------~--~----~ 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 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 -~----------~----~----~----~------~----~------~--~---
