Beautiful README / documentation
williamboxhall opened this issue · 6 comments
I planning to do this eventually...
it should explain the purpose of the library then give a bunch of syntax examples
@fwbrasil I want to start working on this soon. It would be both the README as well as scaladoc in Clump.scala and ClumpSource.scala.
For the README I would like to put a few examples, but how in-depth should it go? In the end, we can link people to the IntegrationSpec.scala for more examples.
In the examples I'd like to cover:
- basic case with a for comprehensions, like this
- one case showing the default filtering when something isn't materialized
- maybe one case showing different filtering with .optional and .orElse ?
For the pre text I guess I would talk about
- What it is (service aggregation in particular abstracting on top of bulk fetching, batching and retries)
- That it is a monad that can be used in for-comprehensions
- That it has been heavily inspired by Twitter's Stitch
anything obvious that I've missed
I guess I should talk about the different ways to create a ClumpSource too
an example of traverse with a for comprehension and just a simple for-comprehension (one using clump.list and one using clump.get)
Cool, we really need a nice readme. I would like to see some initial text more general about what is Clump followed by the usage documentation based on code samples with less text as possible.
I'm also planning to write a separate doc comparing Clump and Stitch.