It could also be be helpful to have links to mailing list discussions or blog postings discussing the reasons for including a method in Clojure or the tradeoffs in using one method vs. another. A few examples:
seq?, sequential? http://groups.google.com/group/clojure/browse_thread/thread/9dbaff59e8de9a8a/9345790eea399af9?lnk=gs fnil, update-in, get-in http://groups.google.com/group/clojure/browse_thread/thread/99cc4a6bfe665a6e promise, deliver http://groups.google.com/group/clojure/browse_frm/thread/0b1548aa40ba8072/210ec81bfe26032e?#210ec81bfe26032e On Jun 29, 8:38 pm, Glen Stampoultzis <gst...@gmail.com> wrote: > On 30 June 2010 10:01, Mark Fredrickson <mark.m.fredrick...@gmail.com> wrote: > > > > > 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. > > > The API/interface is in flux, but the example spells out the basics. > > Call (postdoc var {:key1 value1 :key2 value2 ... }). The hash-map is > > stuffed into the var's metadata, overwriting the doc-string with > > additional information. Other systems could parse the map structure to > > provide clickable links, etc. The system is ad-hoc --- any key is > > valid and keys are used as the dispatching agent for multimethods -- > > so feel free to come up with additional keys. I think we should let > > this grow organically for while before specifying formal semantics. > > > I'm gladly accepting patches, especially for postdoc.clojure.core -- > > the file that documents clojure.core vars (so far, only conj). > > > Check it out, fork it, patch it, use it, enjoy! > > > -Mark > > I think examples on their own without a commentary to go along with > them are somewhat limited. jQuery generally has some good examples of > what detailed API documentation with examples can/should look like > -http://api.jquery.com/change/ > > I think extending the existing documentation with extra information is > potentially a good idea but it needs to be a commentary rather than a > plain example without extra explanation IMHO. -- 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
