I spend some considerable time reverse engineering the module, so I
thought I’d write the documentation I would have liked to see.
The strategy here is that a user not necessarily has insight into how
servant works internally, or even how to write complex servant routes,
they just want to generate a list of endpoints and convert the `Req`
type into e.g. generated code in $language. Thus, they need to know
the semantics of all fields of Req, how they interact and how they
relate to a plain http route.
I made sure every `f` is replaced with `ftype`, so we have one
conventional way of referring to the foreign type argument everywhere.
Some enums are not set at all, they are marked as such.
`_reqBodyContentType` introduces a major restriction of the module, so
that is mentioned in the documentation for now, until the time it will
be fixed.
A few TODO’s describe places where types don’t make sense but would
introduce API-breaking changes, so these should probably be
simplified,
but bundled in one go.
The imports were ordered in the worst possible way, with all
undocumented small type definitions coming first and the actual meat
of the module coming at the very end, mixed in with irrelevant
functions.
This inverses that toxic ordering, showing the main function
first (`listFromAPI`) and then the main data type (`Req`) and the main
class (`HasForeignType`).
We allow a user-specified type to represent the foreign type of haskell
types encountered in the API. This lets users map Integer, Date etc. to
representations other than Text, and have those representations
available in the returned list of Req.
For example, we might want to map a type which has an instance of
Generic to both a foreign type name and a class declaration for that
foreign type such that it can encode/decode itself to JSON. The previous
limitation to a single Text output prevented this case.
* non-messy imports
* got rid of most long lines (>80 chars)
* prisms for sum types and newtypes(we use lens anyway, so why not)
* consistent indentation
