haskell-servant/servant

Better document (just response?) headers

Open

#1,493 opened on Dec 2, 2021

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

Repository metrics

Stars
 (1,953 stars)
PR merge metrics
 (Avg merge 5h 49m) (2 merged PRs in 30d)

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

Research direction
Review existing header documentation and tests in the Servant repository. Identify the gaps for response headers and modifiers like 'noHeader'. Write new tests covering all cases and update the haddock documentation and possibly the tutorial.
Tech stack
None
Domain
backend
Issue type
Documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-2 days
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
Active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
Mostly clear
Prerequisites
HaskellServant
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
70