haskell-servant/servant

Better document (just response?) headers

Open

#1493 opened on Dec 2, 2021

View on GitHub
 (0 comments) (1 reaction) (0 assignees)Haskell (1,953 stars) (422 forks)batch import
documentationenhancementhelp wanted

Description

While we know the effect of Header (and its general variant that allows modifiers) when used for request headers, we don't have much doc or examples when using Headers '[ ... ] in response headers. Whether the response headers necessarily have to be there or not (no, see noHeader), whether modifiers affect the necessity for headers to be there or not, from server & client perspective, etc.

It would be great to have tests that cover all the cases/angles and a slightly more helpful documentation around this whole topic (in the haddocks for sure and perhaps the tutorial/cookbook?).

Contributor guide

Tech stack
None
Domain
documentationbackend
Issue type
documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
half day
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
stale
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
basic knowledge of Servantfamiliarity with Haskell type level programming
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
70
Research direction
Look into the Servant source files that handle response headers, likely in modules like Servant.API.ResponseHeaders or similar. Review existing haddock documentation for Header and Headers types. Add comprehensive tests covering all cases of response headers (required, optional via noHeader, modifiers) and update the tutorial/cookbook with examples. Reference the issue number 1493 for context.