Federico Mena-Quintero
federico@gnome.org 2013
Philip Withnall
philip.withnall@collabora.co.uk 2015
GTK+ 팀
라이브러리 및 API에 문서 추가
조성호
shcho@gnome.org 2016-2018.

# 문서

#

        요약

          API 문서에는 최신의 설정으로 gtk-doc을 활용하십시오().
          문서에 외부 심볼을 넣으려면 XML 엔티티를 활용하십시오().
          모든 API 문서의 익숙함을 유지하려면 일관된 표준 목차를 사용하십시오().
          gtk-doc 빌드에 넣어 D-Bus API 문서를 만들려면 gdbus-codegen을 활용하십시오().
          모든 API 문서에 인트로스펙션 주석을 추가하십시오().
          모든 API 문서에 Since를 추가하십시오().
          gtk-doc 테스트를 활성화하십시오().

# gtk-doc

그놈 라이브러리에 맞는 문서 시스템은 코드의 인라인 주석을 뽑아내어 닥북 문서와 HTML 페이지 모음을 만드는 gtk-doc입니다. 이 내용은 Devhelp에서 살펴볼 수 있습니다. 그놈 기반 대부분은 gtk-doc으로 작성한 문서를 처리하여 만들었습니다.

# 빌드 체계

gtk-doc을 프로젝트 빌드 시스템에 통합하려면 gtk-doc 설명서 절차에 따르십시오. 참고로 sections.txt 파일은 gtk-doc을 실행할 때 처음에 자동으로 나오고, 그 이후에는 만들지 않으며, 직접 최신으로 유지해야합니다. 또한 버전 관리 상태에 두어야합니다.

gtk-doc의 `no-tmpl` 방식을 사용하시고, SGML 대신 XML 모드를 사용해야합니다(tmpl 모드와 SGML 모드는 XML 보다 오래됐으며, 느립니다).

문서의 패키지 버전을 바꿔야한다면, 다음 내용을 넣은 docs/version.xml.in 파일을 만드십시오:

@PACKAGE_VERSION@

위 코드를 configure.ac의 `AC_CONFIG_FILES`에 추가하시고, 문서 상단의 `DOCTYPE`에 `<!ENTITY version SYSTEM "version.xml">`를 넣은 코드를 주 문서 파일(*-docs.xml)에 넣으십시오. 패키지 버전은 `&version;` 처럼 인라인 구문 방식으로 사용할 수 있습니다.

# 표준 배치

동일한 project-name-docs.xml 양식을 사용하는 목차, 섹션, 용어 목록 등에 표준 배치 구성 활용은 프로젝트간에 몇가지 내용이 바뀔 경우 재활용할 수 있습니다. 이는 모든 프로젝트에 걸친 개발자 친화 문서 구성 양식이 유사함을 의미합니다.

다음 형식을 제안합니다:

## project-name-docs.xml

프로젝트의 최상위 gtk-doc 파일 양식

# 라이선스 부여

다양한 곳에 복사할 수 있는 코드 예제가 있을 경우 분명한 API 참고서 라이선스 지정이 중요합니다.

보통 혼동을 방지할 목적으로 프로젝트 코드 자체 용도로 API 참고서에 동일한 라이선스를 적용합니다. 일부 기타 프로젝트는 모든 참고서에 CC-BY-SA 3.0를 적용하기도 합니다. 선택은 여러분의 몫입니다.

표준 배치에서 보여드린 바와 같이, 최상위 gtk-doc 닥북 파일에 문서 라이선스 전문이 들어있는 license.xml을 넣어야합니다.

# 공개용 API

모든 공용 API에는 gtk-doc 주석이 있어야합니다. 함수 주석은 소스 코드 파일의 함수 바로 위에 있어야합니다.

/** * gtk_get_flow: * @widget: a #GtkWidget * * Gets the flow of a widget. * * Note that flows may be laminar or turbulent... * * Returns: (transfer none): the flow of @widget */ GtkFlow * gtk_get_flow (GtkWidget *widget) {

...

}

매크로, 함수 형식, 클래스 구조 등의 문서 주석은, 보통 헤더 파일에서 정의 앞부분에 넣어야합니다.

섹션 도입부는 라이선스 헤더 다음, 설명 대상 소스 파일에 넣어야 합니다:

/** * SECTION:gtksizerequest * @Short_Description: Height-for-width geometry management * @Title: GtkSizeRequest * * The GtkSizeRequest interface is GTK+'s height-for-width (and * width-for-height) geometry management system. * ... */

함수, 매크로, 함수 형식, 구조체 형식을 문서에 넣으려면 문서의 modulename-sections.txt 파일에 넣어야 함을 잊지 마십시오.

새 클래스를 문서에 제대로 기록하려면 modulename-sections.txt에 자체 섹션을 적고, 최상위 modulename-docs.sgml 파일에 넣어야 하며, modulename.types 파일에 작성한 클래스가 나타나도록 `get_type()` 함수를 작성해야합니다.

# 인트로스펙션 주석

각 gtk-doc 주석 부분에는 적절한 GObject 인트로스펙션 주석을 넣어야합니다. 두가지 이유로 활용 가치가 있습니다:

매개변수 형식, NULL 허용 여부, 메모리 관리 관련 중요 정보를 gtk-doc으로 만든 C API 문서에 추가합니다.

공용 API를 파이썬 또는 자바스크립트 등의 기타 언어에 자동으로 바운딩 하도록 해줍니다.

인트로스펙션 주석은 머신에서 해석 가능한 C API에 나타나지 않는 API(함수, 함수 매개변수, 함수 반환 값, 구조체, GObject 속성, GObject 시그널)에 정보를 추가하며, 사람이 알아볼 수 있는 문서 또는 방식으로만 남습니다. 매우 중요한 부분입니다.

gtk-doc 주석은 사람이 알아볼 수 있는 동일한 부분의 내용만 주석으로 남겨야 합니다. 예를 들자면 `NULL` 값을 넣을 수 있는 함수 매개 변수를 문서로 남길 경우, 다른 내용이 아닌 `(nullable)` 주석을 사용하십시오:

/** * my_function: * @parameter: (nullable): some parameter which affects something * * Body of the function documentation. */

다음과 같이 적을 필요는 없습니다:

/** * my_bad_function: * @parameter: some parameter which affects something, or %NULL to ignore * * Bad body of the function documentation. */

인트로스펙션 정보는 인트로스펙션 지침서를 참고하십시오.

# 심볼 버전 부여

공용 API에 심볼을 추가할 때마다 문서 주석도 추가해야합니다. 이 주석에는 새 API를 처음 넣을 패키지 출시 버전 번호를 넣은 `Since` 절을 항상 넣어야합니다. post-release 버전 증가 방식을 활용한다면 configure.ac에 넣은 현재 번호 값이어야합니다.

예제:

/** * my_function: * @param: some parameter * * Body of the function documentation. * * Since: 0.5.0 */

gtk-doc에서는 각 출시판에 추가한 API의 색인을 만들 때 이 정보를 활용합니다. 이 정보는 *-docs.xml 주 파일에 용어 색인처럼 추가해야합니다:

<part> <title>Appendices</title> <index id="api-index-full"> <title>API Index</title> <xi:include href="xml/api-index-full.xml"><xi:fallback/></xi:include> </index> <index id="api-index-deprecated"> <title>Index of deprecated symbols</title> <xi:include href="xml/api-index-deprecated.xml"><xi:fallback/></xi:include> </index> <index role="0.1.0"> <title>Index of new symbols in 0.1.0</title> <xi:include href="xml/api-index-0.1.0.xml"><xi:fallback/></xi:include> </index> <!-- More versions here. --> <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include> </part>

# D-Bus API

D-Bus 인터페이스 설명에는 문서 주석이 들어가며, gdbus-codegen 명령으로 XML에서 빼낼 수 있고, gtk-doc 포함할 DocBook 파일로 전환할 수 있습니다.

다음 코드를 활용하여 DocBook 파일을 메인 *-docs.xml 파일에 넣을 수 있습니다:

<chapter> <title>C Interfaces</title> <partintro> <para>C wrappers for the D-Bus interfaces.</para> </partintro>

<xi:include href="xml/SomeDBusService.xml"/> <xi:include href="xml/SomeOtherService.xml"/> </chapter>

만들어 둔 XML 파일은 gtk-doc Makefile.am 파일의 `content_files` 변수에 넣어야합니다. 안 넣으면 빌드에 실패합니다(`builddir` 값과 `srcdir` 값이 다르면 바꾸십시오).

# 최신 문서 유지

gtk-doc에는 일부 기본 테스트 과정에서 문서 검사를 지원합니다. 문서 검사 과정에서 *-docs.xml 주 파일에 모든 버전의 색인이 있는지, 모든 심볼을 문서에 남겼는지 등을 검사합니다.

gtk-doc Makefile.am 파일에 다음 줄을 추가하여, 이 테스트를 항상 진행할 수 있어야합니다:

TESTS = $(GTKDOC_CHECK)

위 줄을 해당 파일에 추가하면 make check 명령의 일부로 테스트를 실행합니다.