gnome-devel-docs 3.28.0-1 / usr / share / help / ko / programming-guidelines / documentation.page

<?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>&lt;!ENTITY version SYSTEM "version.xml"&gt;</code>를 넣은 코드를 주 문서 파일(<file>*-docs.xml</file>)에 넣으십시오. 패키지 버전은 <code>&amp;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">&lt;part&gt;
	&lt;title&gt;Appendices&lt;/title&gt;
	&lt;index id="api-index-full"&gt;
		&lt;title&gt;API Index&lt;/title&gt;
		&lt;xi:include href="xml/api-index-full.xml"&gt;&lt;xi:fallback/&gt;&lt;/xi:include&gt;
	&lt;/index&gt;
	&lt;index id="api-index-deprecated"&gt;
		&lt;title&gt;Index of deprecated symbols&lt;/title&gt;
		&lt;xi:include href="xml/api-index-deprecated.xml"&gt;&lt;xi:fallback/&gt;&lt;/xi:include&gt;
	&lt;/index&gt;
	&lt;index role="0.1.0"&gt;
		&lt;title&gt;Index of new symbols in 0.1.0&lt;/title&gt;
		&lt;xi:include href="xml/api-index-0.1.0.xml"&gt;&lt;xi:fallback/&gt;&lt;/xi:include&gt;
	&lt;/index&gt;
	&lt;!-- More versions here. --&gt;
	&lt;xi:include href="xml/annotation-glossary.xml"&gt;&lt;xi:fallback /&gt;&lt;/xi:include&gt;
&lt;/part&gt;</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">&lt;chapter&gt;
  &lt;title&gt;C Interfaces&lt;/title&gt;
  &lt;partintro&gt;
    &lt;para&gt;C wrappers for the D-Bus interfaces.&lt;/para&gt;
  &lt;/partintro&gt;

  &lt;xi:include href="xml/SomeDBusService.xml"/&gt;
  &lt;xi:include href="xml/SomeOtherService.xml"/&gt;
&lt;/chapter&gt;</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>