+1 I like it, Justin. I was looking at making something myself but your efforts are farther along. I'd be happy to help with any aspect of this.
Ryan On Fri, Jul 2, 2010 at 2:46 AM, Justin Kramer <jkkra...@gmail.com> wrote: > 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 -- 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
