판별 유니온 Button 은 type 이 submit 이면 color 가, reset 이면 text 가 있다. 코드에서는 type 을 보는 순간 나머지 속성이 정해져 타입 검사와 자동완성이 된다. 그런데 속성 표로 문서화하면 속성마다 한 줄이라 color·text 의 조건을 “type 이 무엇일 때 필수” 라는 글로 적어야 하고, 갈래가 늘면 표가 복잡해진다. 표는 속성 중심, 유니온은 갈래 중심이라 모양이 맞지 않는다. typedoc·api-extractor 로 타입에서 문서를 생성하는 쪽이 낫다.

-- 판별 유니온은 코드엔 좋은데 문서로 옮기기 어렵다
data Button = Submit { color :: String }   -- type: 'submit'
            | Reset  { text  :: String }   -- type: 'reset'
-- 코드: 갈래마다 묶여 있다 — type 을 보면 나머지가 정해진다 (타입 검사·자동완성)

-- 문서 표: 속성마다 한 줄이라 갈래가 조건 문장으로 풀린다
docs = [ ("type",  "'submit' | 'reset'", "필수")
       , ("color", "string", "type = 'submit' 일 때 필수")
       , ("text",  "string", "type = 'reset' 일 때 필수") ]   -- 갈래가 늘면 표가 복잡해진다

-- 그래서 정의 파일을 원본으로 두고 생성한다: typedoc · api-extractor

출처

`#524`