Partly in response to this issue and partly to get my feet wet with Ring and friends, I spent the last few nights writing a proof-of- concept Wiki to collect structured Clojure usage examples:
http://clojure-examples.appspot.com/ Here's a sample function page: http://clojure-examples.appspot.com/clojure.core/contains%3F I tried to come up with something that encourages a many-hands approach while maintaining structure and quality. There are plenty of missing features, but it should be easy for anyone interested to jump in and write some examples. It uses a modified version of Markdown for syntax. Content could be exported/parsed en masse relatively easily. The source is on GitHub: http://github.com/jkk/clj-wiki Does this seem like a worthwhile approach? Justin On Jun 29, 9:35 pm, Mike Meyer <mwm-keyword-googlegroups. 620...@mired.org> wrote: > On Tue, 29 Jun 2010 17:01:10 -0700 (PDT) > > > > > > Mark Fredrickson <mark.m.fredrick...@gmail.com> wrote: > > On Jun 29, 5:43 pm, nickikt <nick...@gmail.com> wrote: > > > We could make it possible to add some metadata to a function > > > like :example or something. Then add a function called (example > > > <function name>) to print the example. > > > > Everybody could send patches. It would be a good way to learn and a > > > good extra doku. > > > I was considering doing this for a while. This thread prompted me to > > put it into action: > > >http://github.com/markmfredrickson/postdoc > > > Here is an example of it in action: > > > (defn foo > > "Adds two numbers" > > [a b] > > (+ a b)) > > > (defn bar > > "Subtracts two numbers" > > [a b] > > (- a b)) > > > (postdoc #'foo > > {:references ["http://foo.com"; "http://bar.com";] > > :examples ['(foo 1 2) '(foo 3 4)] > > :see-also [#'bar] > > :categories [:bar :baz :other]}) > > > user> (doc foo) > > ------------------------- > > user/foo > > ([a b]) > > Adds two numbers > > === Categories === > > > :bar, :baz, :other > > > === See Also === > > > * #'user/bar > > > === Examples === > > > > (foo 1 2) > > 3 > > > (foo 3 4) > > 7 > > > === References === > > > *http://foo.com > > *http://bar.com > > > There is also a (run-examples foo) function that evaluates the > > examples. > > It's a great start. However, examples are much more useful if you know > what they should produce. run-examples might provide that, but having > them in the metadata would be even better - along with an explanation. > > Doing that would allow the examples to be used as a set of unit tests > as well. Nuts, the things you want to test - corner cases and edge > conditions - are among the more useful things to document about a > function. > > <mike > -- > Mike Meyer <m...@mired.org> http://www.mired.org/consulting.html > Independent Network/Unix/Perforce consultant, email for more information. > > O< ascii ribbon campaign - stop html mail -www.asciiribbon.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
