* use Capture Description if available
* update golden/comprehensive.md
This is technically a breaking change, because if a Capture has both a
Description and a ToCapture instance, the Description now takes
precedence. Since this Description wasn't doing anything before, I am
guessing that most projects currently only use Description to describe
their endpoints and not their Captures, and thus that few people will be
affected by this breaking change.
* test the "no ToCapture instance" case
The case in which there is both a Description and a ToCapture instance
seems like a corner case. The more interesting cases are the one in
which there is a Description but no ToCapture instance, and the case in
which there is a ToCapture instance but no description.
Servant supports defining the same route multiple times with different
content-types and result-types, but servant-docs was only documenting
the first of copy of such duplicated routes. It now combines the
documentation from all the copies.
Unfortunately, it is not yet possible for the documentation to specify
multiple status codes.
- Introduce SourceT, which is simple variant of "correct `ListT`".
There are another variants possible (like in `streaming`),
but I'm not sure there's much real difference.
- Introduce `Codensity`. There's a flag if people don't want to depend
on `kan-extensions`.
- `StreamGenerator` and `ResultStream` are both `SourceT`.
`Stream` combinator in `servant-client` uses `Codensity` for CPS.
- Add servant-machines, servant-conduit, servant-pipes
- Add streaming cookbook: just code, no explanations.
- Add a script to run streaming 'benchmarks'
- Add Streaming endpoint to the comprehensive API.
- Rename BuildFromStream to FromResultStram
- I'm tempted to rename everything in the Servant.API.Stream
(add some prefixes, `header` is too good name to steal)
The TODO in `servant-docs` is left intentionally.
Changes Header, ReqBody and QueryParam to take a modifier list.
Resolves https://github.com/haskell-servant/servant/issues/856
ResponseHeader story turns to be somewhat ugly, but it can be made
elegant when https://github.com/haskell-servant/servant/issues/841 is
implemnted, then we can omit HList aka Header Heterogenous List
implementation.
- servant-server changes:
Writing server side intepretations is quite simple using
`unfoldRequestArgument`, which makes Header and QueryParam look quite
the same.
`ReqBody` cannot be easily made optional with current design (what that
would mean: No Content-Type Header?), so that dimensions isn't used
there.
- Add HasLink for all the rest ComprehensiveAPI combinators
- Add 'tricky' Header', QueryParam' endpoints to ComprehensiveAPI
- servant-docs: Quick'n'dirty implementation. Don't use modifiers information (yet).
For some reason, 2nd-level headings are used for introductions and for
each API endpoint, but then it immediately jumps to 4th-level
headings.
Instead, promote everything that's 4th-level to 3rd-level.
This relies on the behaviour of pandoc, and as such may not apply to
other Markdown renderers.
Before this change, you would have something like:
> - Example: `application/json`
>
> ```javascript
> "HELLO, HASKELLER"
> ```
When converting this to HTML, PDF, etc. the code block is _not_
contained within the bullet point.
With this change, the generated markdown looks like:
> - Example: `application/json`
>
> ```javascript
> "HELLO, HASKELLER"
> ```
With pandoc at least, this effectively indents the entire code block
to be under the bullet point, which is the intended effect.
Note that the code itself is _not_ indented (which might break other
Markdown renderers) as to do so would require splitting on newlines,
which may have unintended consequences when dealing with generated
values (may contain `\r\n`, etc.).
Currently, it appears after the notes, authentication and capture
information... such that if any of those exist, then the list of
header sensitivity will appear to be an item of one of the previous
ones (as they provide Markdown headers).
As reported in #754, `HasDocs` instance of `ReqBody` was dropping samples other
than the first one. With this patch we show at most `_maxSamples` samples for
`ReqBody`, and also include the sample title in the docs.
