append testcases to docstring? (or improve REPL experience)

zcaudate-me / lein-midje-doc

moved -> 'lucid.publish'

http://docs.caudate.me/lucidity/lucid-publish.html

73 stars 8 forks source link

append testcases to docstring? (or improve REPL experience) #4

Closed myguidingstar-zz closed 10 years ago

myguidingstar-zz commented 11 years ago

I find lein-midje-doc the right way to do literate programming. But during playing around REPL the test cases should be accessible, too. I can think of two approaches:

automatically append test cases to docstring (update metadata)
provide an other form rather than (doc a-symbol), for example (test-doc a-symbol)

(Sorry if this question is silly because I myself haven't try lein-midje-doc yet)

zcaudate commented 11 years ago

That's not a trivial thing to do.. But it definitely is possible

figure out the var using current namespace and symbol name
go through a test file to see if the var has any entries
display the entries in the console

(usage add) => (add 1 1) -> 2

Would you be interested in helping with the implementation?

On 26/11/2013, at 15:28, Hoàng Minh Thắng notifications@github.com wrote:

I find lein-midje-doc the right way to do literate programming. But during playing around REPL the test cases should be accessible, too. Two approaches:

automatically append test cases to docstring (update metadata) provide an other form rather than (doc a-symbol), for example (test-doc a-symbol) (Sorry if this question is silly because I myself haven't try lein-midje-doc yet) — Reply to this email directly or view it on GitHub.

myguidingstar-zz commented 11 years ago

After a bit more thinking and research:

I prefer not touching docstrings and provide usage independently
REPL usage command is most useful for other's libraries (dependencies), not your own projects (where you usually have them all in your head). But lein doesn't package tests => we need a way to make usage data available in source, not test.
my current solution is to make a hook into lein's packaging process and generate a conventional file that stores usage data

What do you think?

zcaudate commented 11 years ago

Hmmm... That's a good point. A kind of a hack would be to add an extra :usage key to project.clj and then have a list of generated files. Another way is to generate the usage file within the resource directory and automatically load that.

zcaudate commented 10 years ago

I've added this functionality as of 0.0.21. Documentation and hardening of these features will come later but they are currently usable (though expect some bugs). I will add fixes as they come up