<?xml version="1.0" encoding="utf-8"?>
<page xmlns="http://projectmallard.org/1.0/" xmlns:its="http://www.w3.org/2005/11/its" xmlns:xi="http://www.w3.org/2003/XInclude" type="topic" id="documentation" xml:lang="ko">
<info>
<link type="guide" xref="index#general-guidelines"/>
<credit type="author copyright">
<name>Federico Mena-Quintero</name>
<email its:translate="no">federico@gnome.org</email>
<years>2013</years>
</credit>
<credit type="author copyright">
<name>Philip Withnall</name>
<email its:translate="no">philip.withnall@collabora.co.uk</email>
<years>2015</years>
</credit>
<credit type="author copyright">
<name>GTK+ 팀</name>
</credit>
<include xmlns="http://www.w3.org/2001/XInclude" href="cc-by-sa-3-0.xml"/>
<desc>라이브러리 및 API에 문서 추가</desc>
<mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
<mal:name>조성호</mal:name>
<mal:email>shcho@gnome.org</mal:email>
<mal:years>2016, 2017.</mal:years>
</mal:credit>
</info>
<title>문서</title>
<synopsis>
<title>요약</title>
<list>
<item><p>API 문서에는 최신의 설정으로 gtk-doc을 활용하십시오(<link xref="#gtk-doc"/>).</p></item>
<item><p>문서에 외부 심볼을 넣으려면 XML 엔티티를 활용하십시오(<link xref="#build-system"/>).</p></item>
<item><p>모든 API 문서의 익숙함을 유지하려면 일관된 표준 목차를 사용하십시오(<link xref="#standard-layout"/>).</p></item>
<item><p>gtk-doc 빌드에 넣어 D-Bus API 문서를 만들려면 <cmd>gdbus-codegen</cmd>을 활용하십시오(<link xref="#dbus-api"/>).</p></item>
<item><p>모든 API 문서에 인트로스펙션 주석을 추가하십시오(<link xref="#introspection-annotations"/>).</p></item>
<item><p>모든 API 문서에 <code>Since</code>를 추가하십시오(<link xref="#symbol-versioning"/>).</p></item>
<item><p>gtk-doc 테스트를 활성화하십시오(<link xref="#keeping-up-to-date"/>).</p></item>
</list>
</synopsis>
<section id="gtk-doc">
<title>gtk-doc</title>
<p>그놈 라이브러리에 맞는 문서 시스템은 코드의 인라인 주석을 뽑아내어 <link href="http://docbook.org/">닥북</link> 문서와 HTML 페이지 모음을 만드는 <link href="http://www.gtk.org/gtk-doc/">gtk-doc</link>입니다. 이 내용은 <link href="https://wiki.gnome.org/Apps/Devhelp">Devhelp</link>에서 살펴볼 수 있습니다. 그놈 기반 대부분은 gtk-doc으로 작성한 문서를 처리하여 만들었습니다.</p>
</section>
<section id="build-system">
<title>빌드 체계</title>
<p>gtk-doc을 프로젝트 빌드 시스템에 통합하려면 <link href="https://developer.gnome.org/gtk-doc-manual/stable/settingup.html.en">gtk-doc 설명서 절차</link>에 따르십시오. 참고로 <file>sections.txt</file> 파일은 gtk-doc을 실행할 때 처음에 자동으로 나오고, 그 이후에는 만들지 않으며, 직접 최신으로 유지해야합니다. 또한 <link href="https://developer.gnome.org/gtk-doc-manual/stable/settingup_vcs.html.en">버전 관리</link> 상태에 두어야합니다.</p>
<p>gtk-doc의 <code>no-tmpl</code> 방식을 사용하시고, SGML 대신 XML 모드를 사용해야합니다(tmpl 모드와 SGML 모드는 XML 보다 오래됐으며, 느립니다).</p>
<p>문서의 패키지 버전을 바꿔야한다면, 다음 내용을 넣은 <file>docs/version.xml.in</file> 파일을 만드십시오:</p>
<code>@PACKAGE_VERSION@</code>
<p>위 코드를 <file>configure.ac</file>의 <code>AC_CONFIG_FILES</code>에 추가하시고, 문서 상단의 <code>DOCTYPE</code>에 <code><!ENTITY version SYSTEM "version.xml"></code>를 넣은 코드를 주 문서 파일(<file>*-docs.xml</file>)에 넣으십시오. 패키지 버전은 <code>&version;</code> 처럼 인라인 구문 방식으로 사용할 수 있습니다.</p>
</section>
<section id="standard-layout">
<title>표준 배치</title>
<p>동일한 <file><var>project-name</var>-docs.xml</file> 양식을 사용하는 목차, 섹션, 용어 목록 등에 표준 배치 구성 활용은 프로젝트간에 몇가지 내용이 바뀔 경우 재활용할 수 있습니다. 이는 모든 프로젝트에 걸친 개발자 친화 문서 구성 양식이 유사함을 의미합니다.</p>
<p>다음 형식을 제안합니다:</p>
<listing>
<title><file><var>project-name</var>-docs.xml</file></title>
<desc>프로젝트의 최상위 gtk-doc 파일 양식</desc>
<code mime="application/docbook+xml"><xi:include href="example-docs.xml" parse="text"/></code>
</listing>
</section>
<section id="licensing">
<title>라이선스 부여</title>
<p>다양한 곳에 복사할 수 있는 코드 예제가 있을 경우 분명한 API 참고서 라이선스 지정이 중요합니다.</p>
<p>보통 혼동을 방지할 목적으로 프로젝트 코드 자체 용도로 API 참고서에 동일한 라이선스를 적용합니다. 일부 기타 프로젝트는 모든 참고서에 CC-BY-SA 3.0를 적용하기도 합니다. 선택은 여러분의 몫입니다.</p>
<p><link xref="#standard-layout">표준 배치</link>에서 보여드린 바와 같이, 최상위 gtk-doc 닥북 파일에 문서 라이선스 전문이 들어있는 <file>license.xml</file>을 넣어야합니다.</p>
</section>
<section id="public-api">
<title>공개용 API</title>
<p>모든 공용 API에는 gtk-doc 주석이 있어야합니다. 함수 주석은 소스 코드 파일의 함수 바로 위에 있어야합니다.</p>
<code mime="text/x-csrc" style="valid">/**
* 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)
{
...
}</code>
<p>매크로, 함수 형식, 클래스 구조 등의 문서 주석은, 보통 헤더 파일에서 정의 앞부분에 넣어야합니다.</p>
<p>섹션 도입부는 라이선스 헤더 다음, 설명 대상 소스 파일에 넣어야 합니다:</p>
<code mime="text/x-csrc" style="valid">/**
* 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.
* ...
*/</code>
<p>함수, 매크로, 함수 형식, 구조체 형식을 문서에 넣으려면 문서의 <file>modulename-sections.txt</file> 파일에 넣어야 함을 잊지 마십시오.</p>
<p>새 클래스를 문서에 제대로 기록하려면 <file>modulename-sections.txt</file>에 자체 섹션을 적고, 최상위 <file>modulename-docs.sgml</file> 파일에 넣어야 하며, <file>modulename.types</file> 파일에 작성한 클래스가 나타나도록 <code>get_type()</code> 함수를 작성해야합니다.</p>
</section>
<section id="introspection-annotations">
<title>인트로스펙션 주석</title>
<p>각 gtk-doc 주석 부분에는 적절한 <link href="https://wiki.gnome.org/Projects/GObjectIntrospection/Annotations"> GObject 인트로스펙션 주석</link>을 넣어야합니다. 두가지 이유로 활용 가치가 있습니다:</p>
<list type="numbered">
<item><p>매개변수 형식, NULL 허용 여부, 메모리 관리 관련 중요 정보를 gtk-doc으로 만든 C API 문서에 추가합니다.</p></item>
<item><p>공용 API를 파이썬 또는 자바스크립트 등의 기타 언어에 자동으로 바운딩 하도록 해줍니다.</p></item>
</list>
<p>인트로스펙션 주석은 머신에서 해석 가능한 C API에 나타나지 않는 API(함수, 함수 매개변수, 함수 반환 값, 구조체, GObject 속성, GObject 시그널)에 정보를 추가하며, 사람이 알아볼 수 있는 문서 또는 방식으로만 남습니다. 매우 중요한 부분입니다.</p>
<p>gtk-doc 주석은 사람이 알아볼 수 있는 동일한 부분의 내용만 주석으로 남겨야 합니다. 예를 들자면 <code>NULL</code> 값을 넣을 수 있는 함수 매개 변수를 문서로 남길 경우, 다른 내용이 아닌 <code>(nullable)</code> 주석을 사용하십시오:</p>
<code mime="text/x-csrc" style="valid">/**
* my_function:
* @parameter: (nullable): some parameter which affects something
*
* Body of the function documentation.
*/</code>
<p>다음과 같이 적을 필요는 없습니다:</p>
<code mime="text/x-csrc" style="invalid">/**
* my_bad_function:
* @parameter: some parameter which affects something, or %NULL to ignore
*
* Bad body of the function documentation.
*/</code>
<p>인트로스펙션 정보는 <link xref="introspection">인트로스펙션 지침서</link>를 참고하십시오.</p>
</section>
<section id="symbol-versioning">
<title>심볼 버전 부여</title>
<p>공용 API에 심볼을 추가할 때마다 문서 주석도 추가해야합니다. 이 주석에는 새 API를 처음 넣을 패키지 출시 버전 번호를 넣은 <code>Since</code> 절을 항상 넣어야합니다. <link xref="versioning#release-process">post-release 버전 증가 방식</link>을 활용한다면 <file>configure.ac</file>에 넣은 현재 번호 값이어야합니다.</p>
<p>예제:</p>
<code mime="text/x-csrc" style="valid">/**
* my_function:
* @param: some parameter
*
* Body of the function documentation.
*
* Since: 0.5.0
*/</code>
<p>gtk-doc에서는 각 출시판에 추가한 API의 색인을 만들 때 이 정보를 활용합니다. 이 정보는 <file>*-docs.xml</file> 주 파일에 용어 색인처럼 추가해야합니다:</p>
<code mime="application/docbook+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></code>
</section>
<section id="dbus-api">
<title>D-Bus API</title>
<p>D-Bus 인터페이스 설명에는 문서 주석이 들어가며, <cmd>gdbus-codegen</cmd> 명령으로 XML에서 빼낼 수 있고, gtk-doc 포함할 DocBook 파일로 전환할 수 있습니다.</p>
<p>다음 코드를 활용하여 DocBook 파일을 메인 <file>*-docs.xml</file> 파일에 넣을 수 있습니다:</p>
<code mime="application/docbook+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></code>
<p>만들어 둔 XML 파일은 gtk-doc <file>Makefile.am</file> 파일의 <code>content_files</code> 변수에 넣어야합니다. 안 넣으면 빌드에 실패합니다(<code>builddir</code> 값과 <code>srcdir</code> 값이 다르면 바꾸십시오).</p>
</section>
<section id="keeping-up-to-date">
<title>최신 문서 유지</title>
<p>
gtk-doc comes with support for checking the documentation with some basic
tests. These check that all version indexes are included in the main
<file>*-docs.xml</file> file and that all symbols are documented, among
other things.
</p>
<p>gtk-doc <file>Makefile.am</file> 파일에 다음 줄을 추가하여, 이 테스트를 항상 진행할 수 있어야합니다:</p>
<code>TESTS = $(GTKDOC_CHECK)</code>
<p>위 줄을 해당 파일에 추가하면 <cmd>make check</cmd> 명령의 일부로 테스트를 실행합니다.</p>
</section>
</page>