I would LOVE to have simple examples for all functions, anyplace that makes them easy to access during coding. In docstrings would be fine with me, but other places would work as well.
Here again the Processing project (among others, I'm sure) provides a nice example IMHO, even though Processing and Clojure are obviously very different beasts. For each Processing function there's a web page with a description and a simple example. For example http://processing.org/reference/ellipse_.html . From the IDE you can jump instantly to a local copy of the page for any function by highlighting it and selecting "Find in Reference" -- of course in Clojure people will be using different IDEs or none at all, so the integration with the coding environment might not always be this smooth, but the important thing is that you can get most of what you need for most uses of the function, including an example, in one place that's easy to find. By contrast, with Clojure I often end up puzzling over descriptions that require me to do more hunting to understand what some of the terms mean, or looking through source code, etc. This is perfectly understandable considering Clojure's youth and scope, and the focus of the developers on other things. But I think that this kind of model would be very nice to aim for, especially as a way to help beginners. -Lee On Jun 29, 2010, at 3:13 AM, Tom Faulhaber wrote: > I like the idea of having example code for all the functions. > > However, speaking for myself only, I don't think that the doc strings > are the place for a comprehensive set of examples. > > How about building them in some external place? (Maybe as a separate > github project to begin with.) In particular, it would be nice if the > examples used some literate programming technique that let users open > the examples and play with them. That way, they could be linked to > from the documentation (I could roll it into autodoc, for instance, > subject to Rich and Stuart's constraints) but also directly opened, > tried, copied, etc. from your editor and repl. > > It's easy for me to imagine that, in the not too distant future, we > could roll that into Clojure core in a way similar to the tests. > > Tom -- Lee Spector, Professor of Computer Science School of Cognitive Science, Hampshire College 893 West Street, Amherst, MA 01002-3359 lspec...@hampshire.edu, http://hampshire.edu/lspector/ Phone: 413-559-5352, Fax: 413-559-5438 Check out Genetic Programming and Evolvable Machines: http://www.springer.com/10710 - http://gpemjournal.blogspot.com/ -- 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
