[racket] Pull some rackunit tests into Scribble doc as examples?

From: Greg Hendershott (greghendershott at gmail.com)
Date: Thu Dec 15 07:54:12 EST 2011

I'm trying to finish a couple PLaneT packages. Want to contribute
something back, finally. (One is a package for quite a few Amazon Web
Services, including S3, SES, SDB, SQS, SNS, and CloudWatch. The other
is an HTTP 1.1 library, only because I want some 1.1-ness for the
former.)

Although I'm nervous about flubbing this, I think it's almost ready to
go. One of the last things I'm doing is polishing the docs I've been
writing along the way.

So:

I want the docs to include plenty of examples, because generally I
learn much faster that way.

I'm noticing that a big subset of my rackunit tests would also be
reasonably good examples. Albeit clearer if `check-equal?' and
`check-true' were stripped out.

Plus I like the idea that the unit tests should include correctly
running the examples in the docs. :)

So:

- On the one hand, seems unfortunate to do via big copy/paste/modify
exercise: Copy from multiple rkt to scrbl, edit to strip the (check-
...), etc.  Plus hard to maintain if tests added/changed.

- On the other hand, I should probably release the packages, not get
detoured by figuring out some supposedly elegant solution to this
myself. :)

- Is there a third hand?  Has anyone already done this, or, already
see how this would be simple to do?

Ideally it would be something like @examples/test-case[
<test-case-name> ], which strips off the check-* parts, and uses that
as an expression for a normal Scribble example?

Thank you.


Posted on the users mailing list.