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. --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
