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
