On Tue, 29 Jun 2010 17:01:10 -0700 (PDT)
Mark Fredrickson <[email protected]> wrote:
> On Jun 29, 5:43 pm, nickikt <[email protected]> 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 <[email protected]> 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 [email protected]
Note that posts from new members are moderated - please be patient with your
first post.
To unsubscribe from this group, send email to
[email protected]
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
