haskell-servant / haskell-servant/servant

servant-docs: Modify the Description combinator instance of HasDocs

Open
#1,026 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.