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. 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 -- 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
