[DBUS] gdbus-codegen 명령어로 API Docs(Documentation) 생성하기

gdbus-codegen 명령어로 documentation (XML 파일)을 생성하고 이를 HTML 파일로 나타내보자.

 

STEP 1. 패키지 설치하기

(1) libglib2.0-dev 패키지

먼저 gdbus-codegen 명령어를 실행하기 위해 libglib2.0-dev 패키지를 설치한다.

# 설치
sudo apt-get update
sudo apt-get install libglib2.0-dev

# 또는
sudo apt-get install libglib2.0-dev-bin

 

이후 아래 명령어로 설치확인을 해보자

# gdbus-codegen 존재 확인
which gdbus-codegen
# 예상 출력: /usr/bin/gdbus-codegen

# 버전 확인
# gdbus-codegen은 GLib의 일부이므로 버전이 동일
pkg-config --modversion glib-2.0
# 예상 출력: 2.72.4

 

(2) gtk-doc-tools 패키지

xml을 html로 변환하기 위해 gtk-doc 명령어를 써야하는데, 그러기 위해 필요한 패키지를 설치한다.

sudo apt install gtk-doc-tools

 

STEP 2. gdbus-codegen 명령어로 xml 형태의 Docs 생성

먼저 예제 DBus Instropection XML 파일을 생성하자

- org.example.Calculator.xml

<!DOCTYPE node PUBLIC
"-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
<node name="/" xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd">
  <interface name="org.example.Calculator">
      <!--
        Add:
        @a: The first double-precision floating-point number.
        @b: The second double-precision floating-point number.
        @result: The calculated sum of the two inputs.
        @response: server staus
        The @response indicates the server status:
        <simplelist>
              <member>0: Success, the request is carried out</member>
              <member>1: Server cancelled the interaction</member>
              <member>2: Sever interaction was ended in some other way</member>
        </simplelist>
        In the case of an error (response 2) @results may contain wrong value

        Computes the sum of @a and @b.
      -->
  	<method name="Add">
      <arg name="a" type="d" direction="in">
      </arg>
      <arg name="b" type="d" direction="in">
      </arg>
      <arg name="result" type="d" direction="out">
      </arg>
      <arg name="response" type="d" direction="out">
      </arg>
    </method>
	<!--
        Subtract:
        @a: The minuend (value to be subtracted from).
        @b: The subtrahend (value to subtract).
        @result: The arithmetic difference.

        Subtracts @b from @a and returns the difference.
  	-->
    <method name="Subtract">
      <arg name="a" type="d" direction="in" />
      <arg name="b" type="d" direction="in" />
      <arg name="result" type="d" direction="out" />
    </method>
    
	<!--
        CalculationFinished:
        @operation: A string representing the method name (e.g., "Add").

        Emitted when a calculation is successfully completed.

        Example @version:
        <variablelist>
          <varlistentry>
            <term>version s</term>
             <listitem><para>
             Version is version.
            </para></listitem>
          </varlistentry>
          <varlistentry>
            <term>isStable b</term>
            <listitem><para>
            chekc if It's stable or not
            </para></listitem>
          </varlistentry>
	</variablelist>
	Example description (@operation is good):

	Example description (@operation is good):

	Example description (@operation is good):
	-->
    <signal name="CalculationFinished">
      <arg name="operation" type="s">
      </arg>
    </signal>
  </interface>
</node>

 

이후 해당 org.example.Calculator.xml파일이 위치한 곳에서,

gdbus-codegen 명령어를 실행한다.

gdbus-codegen --generate-docbook=docs \
org.example.Calculator.xml

 

이렇게하면 docs-org.example.Calculator.xml 파일이 생성될 것이다.

STEP 3. Docs XML파일을 HTML로 변환하기

docs-org.example.Calculator.xml 파일이 있는 위치에서 아래의 명령어를 실행한다

mkdir -p html
cd html
gtkdoc-mkhtml docs ../docs-org.example.Calculator.xml

 

 

STEP 4. index.html 파일 실행하기

생성된 index.html파일을 실행하면 아래와 같이 API Docs가 생성된 걸 확인할 수 있다.

 

 

 

Reference

https://github.com/flatpak/flatpak/blob/c27af8a9d90af5573b74f832a079a498caf5d1d1/data/org.freedesktop.Flatpak.Authenticator.xml#L26