haskell-servant / haskell-servant/servant
servant-docs: Modify the Description combinator instance of HasDocs
- Dominant language
- Haskell
- Stars
- 2k
- Forks
- 427
- Avg merge
- 2d 23h
- Merged PRs (30d)
- 5
Description
The value of the `Description` combinator can be fairly long unlike that of the similar `Summary` combinator.
However, the `HasDocs` instance of the `Description` combinator does the same thing as the `HasDocs` instance of the `Summary` combinator - they both put the entire value of the symbol in the `_noteTitle` of a `DocNote`:
https://github.com/haskell-servant/servant/blob/46973b7ccfe090d7f0097968b9a9e2fc8446d3d2/servant-docs/src/Servant/Docs/Internal.hs#L942
https://github.com/haskell-servant/servant/blob/46973b7ccfe090d7f0097968b9a9e2fc8446d3d2/servant-docs/src/Servant/Docs/Internal.hs#L952
This means that:
1. if a long API description is provided, it ends up as a long `_noteTitle`. If it includes newlines, this does not look so bad when output with the `markdown` function, since the first line of the description becomes the markdown title and the rest of it effectively becomes a body. This does _not_ work for docs rendered by servant-pandoc.
2. the generated docs may look odd when both a summary and description are provided. They are two `DocNotes` that only have `_noteTitles` mixed in with all the `DocNotes` with no guarantee that summary immediately precedes the description.
Options for fixing this:
a. Simplest:
* split the Description value on newlines
* its first line is `_noteTitle`, and its remaining lines are `_noteBody`
* solves 1, but not 2
b. And an new instance (an overlapping one?) for when a `Description` immediately follows a `Summary`
* add a single `DocNote`; the summary provides the `_noteTitle`, the `_noteBody` is the description split on newlines
* solves 2, only solves 1 when a `Summary` always precedes a `Description`
c. both a and b
Contributor guide
Assessment
This issue has not been assessed yet.