i was talking about something related in the chat group, but I'm not good enough yet to implement it. I want to rewrite the doc method slightly in a way that would go a LONG way for newbies. The current way actually looks like java . . . like the parens are around the input params. But that's just a side effect of having called (:arglists <somefunc>)
Instead, showing the context of the function name and all would be awesome . . . it would look like a java, c or c++ prototype: so the doc for doall would look like it does now, but replace the arglist printout with: (defn doall [lazy_coll] ... [n lazy_coll] ...) -> in_mem_coll or something like that (I'm not even sure that's exactly right for doall). Show the function name, the various parameter choices, AND a descriptive variable name for what gets returned. That might help in the categorization challenge, too. define things by what they take and what they return. Before the folks in the chat room explained what (:arglists ...) was even doing for me, I was sort of forced to kind of ignore it ... which left me high and dry whenever the text description was omitted. On Sun, Feb 1, 2009 at 3:25 PM, Mark Addleman <mark_addle...@bigfoot.com>wrote: > > More as a note to future Clojure doc'ers than anything else: It seems > that noobies (including myself) get bitten by the lazy versus > immediate evaluation functions all the time (e.g. for versus doseq/ > doall). If this problem isn't solved through naming conventions > (probably way too tedious to be valuable), then I suggest it be solved > through doc tagging. Of course, then an IDE could color lazy and > immediate forms differently. > > On Jan 20, 1:17 pm, lpetit <laurent.pe...@gmail.com> wrote: > > Hello, > > > > As modest as this could be in the quest of a formal categorization, I > > find the integrated string pattern search integrated into clojuredev > > really useful, so I can't resist to do this shameless plug. > > > > You can see it in action, with a search on the word "string", either > > by searching the word in symbol names or also in symbols functions, at > > this link : > http://code.google.com/p/clojure-dev/wiki/ScreenShots#Namespace_Brows... > > > > What I think makes it really usefull is that it's fast, compared to > > going to your browser, launching the API page of the clojure website, > > and searching for the word string through the entire page. > > And you have the args and doc string as a tooltip when hovering over a > > symbol. > > > > Of course, if some sort of categorization is done on symbols, maybe > > via a project that could make a pass on existing symbols and enhance > > their metadata with lists of Strings, this would be an enhancement > > interesting to incorporate into an IDE (or even a command-line REPL), > > for sure ! > > > > See you, > > > > -- > > Laurent > > > > On 20 jan, 21:42, Mark Volkmann <r.mark.volkm...@gmail.com> wrote: > > > > > On Tue, Jan 20, 2009 at 10:09 AM, MarkAddleman > > > > > <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 athttp:// > 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 -~----------~----~----~----~------~----~------~--~---
