Haskell 문서화 도구 Haddock의 개요와, 모듈의 내보내기 목록을 활용해 문서를 계층적으로 구성하고 목차를 생성하는 방법을 설명합니다.
목차
Haddock은 Haskell을 위한 문서화 도구입니다.
Haddock은 대부분의 언어 문서화 시스템보다 생태계에 더 깊이 얽혀 있습니다. 중앙 패키지 저장소인 Hackage는 HTML 문서를 오직 Haddock으로만 생성하고, Cabal과 Stack에는 Haddock 지원이 내장되어 있습니다. Hackage에 업로드할 라이브러리를 작성한다면 Haddock을 사용할 수밖에 없습니다.
Haddock은 각 모듈에 대해 해당 모듈이 내보내는 모든 항목을 나열한 페이지를 자동으로 제공합니다. 그중 중요한 내용은 다음과 같습니다.
각 문서 항목에는 해당 항목이 정의된 소스 코드 위치로 이동하는 링크도 포함됩니다.
Haddock의 흥미로운 기능 중 하나는 라이브러리 사용자에게 타입과 함수들을 따분한 알파벳 순 목록으로만 보여주지 않는다는 점입니다. 대신 계층적 섹션 제목과 목차를 가진 문서 형태로 구성할 수 있게 해줍니다.
이 모든 것은 모듈의 내보내기 목록(export list) 안에서 이루어집니다. 내보내기 목록은 모듈의 API를 정의합니다. 즉, 소스 파일에 정의된 것들 중 어떤 것이 모듈 밖의 코드에서 보이게 될지를 결정합니다.
module Your.Module.Name
(
-- 모듈의 내보내기 목록은
-- 괄호 안의 모든 것으로 구성됩니다.
-- 여기에서 Haddock 문서의 구조를
-- 제어합니다.
) where
Haddock이 생성하는 문서의 모든 항목은 모듈의 내보내기 목록에 적힌 순서를 따릅니다. 소스 코드의 그 밖의 부분이 어떤 순서로 되어 있는지는 문서에 아무런 영향을 주지 않습니다.
문서를 섹션으로 나누는 방법은 내보내기 목록 사이사이에 섹션 헤더를 끼워 넣는 것입니다. 하나 이상의 * 문자로 시작하는 주석은 헤더로 해석됩니다. *는 섹션, **는 하위 섹션을 의미하며, 계속해서 더 깊어질 수 있습니다. 이는 Markdown에서 # 문자로 제목을 표시하는 방식과 유사합니다.
예를 들어, 아래는 내보내기 목록 예시와 Haddock이 생성할 목차 결과입니다. 이 예시는 인기 있는 웹 클라이언트 라이브러리인 wreq에서 가져온 것이지만, 설명을 위해 많은 부분을 생략했습니다.
module Network.Wreq
(
-- * HTTP 동사
-- ** GET
get
, getWith
-- ** POST
, post
, postWith
-- * 설정
, Options
, defaults
-- ** 인증
, Auth, basicAuth, oauth1Auth
, oauth2Bearer, oauth2Token
-- ** 프록시 설정
, Proxy (..), httpProxy
)
HTTP 동사
설정