Writing Kernel-doc Comments

kernel-doc 주석의 목적과 적용 범위

Linux 커널 소스 파일에는 함수, 타입, 코드 설계를 설명하는 구조화된 `kernel-doc` 형식의 문서 주석을 넣을 수 있습니다. 문서를 소스 파일 안에 두면 코드와 함께 최신 상태로 유지하기가 더 쉽습니다.

`kernel-doc` 형식은 겉보기에는 javadoc, gtk-doc, Doxygen과 비슷하지만 역사적인 이유로 명확히 다른 규칙을 사용합니다. 커널 소스에는 수만 개의 kernel-doc 주석이 있으므로 이 문서에서 설명하는 스타일을 따라야 합니다. Rust 코드는 kernel-doc 대상이 아니며 `Documentation/rust/general-information.rst`를 참고해야 합니다.

도구는 주석에서 kernel-doc 구조를 추출하고 anchor가 붙은 올바른 `Sphinx C Domain` 함수·타입 설명을 생성합니다. 설명에 있는 kernel-doc 전용 강조 표기와 교차 참조도 변환합니다. Sphinx C Domain 문서는 `http://www.sphinx-doc.org/en/stable/domains.html`에서 확인할 수 있습니다.

로드 가능한 모듈에 `EXPORT_SYMBOL` 또는 `EXPORT_SYMBOL_GPL`로 내보내는 모든 함수에는 kernel-doc 주석이 있어야 합니다. 모듈이 사용하도록 의도한 헤더 파일의 함수와 자료 구조도 마찬가지입니다.

`static`으로 표시하지 않아 다른 커널 파일에서 볼 수 있는 함수에도 kernel-doc 형식 문서를 제공하는 것이 좋습니다. 소스 배치를 일관되게 유지하려면 파일 전용 `static` 루틴에도 문서를 작성하는 것이 권장되지만, 우선순위는 더 낮으며 해당 소스 파일 maintainer의 판단에 따릅니다.

주석 배치와 형식 검사

kernel-doc 주석은 여는 표식 `/**`로 시작합니다. `kernel-doc` 도구는 이 표식이 있는 주석을 추출합니다. 나머지는 왼쪽에 별표 열을 둔 일반 여러 줄 주석처럼 작성하고, 별도 줄의 `*/`로 닫습니다.

함수와 타입을 설명하는 주석은 코드 변경자가 문서도 함께 바꿀 가능성을 높이도록 대상 함수나 타입 바로 앞에 둡니다. 개요용 kernel-doc 주석은 최상위 들여쓰기 수준의 어느 위치에나 둘 수 있습니다.

실제 출력을 생성하지 않고 `kernel-doc`의 상세 출력을 높여 주석 형식을 검사할 수 있습니다.

scripts/kernel-doc -v -none drivers/foo/bar.c

커널 빌드에 추가 gcc 검사를 요청하면 문서 형식도 검증됩니다. `n`은 원하는 경고 수준으로 바꿉니다.

make W=n

함수와 함수형 매크로 문서

함수 및 함수형 매크로의 kernel-doc 주석은 함수 이름과 짧은 설명, 순서대로 나열한 인수 설명, 선택적인 긴 설명, 호출 문맥, 반환값 설명으로 구성합니다.

/**
 * function_name() - Brief description of function.
 * @arg1: Describe the first argument.
 * @arg2: Describe the second argument.
 *        One can provide multiple line descriptions
 *        for arguments.
 *
 * A longer description, with more discussion of the function function_name()
 * that might be useful to those using or modifying it. Begins with an
 * empty comment line, and may include additional embedded empty
 * comment lines.
 *
 * The longer description may have multiple paragraphs.
 *
 * Context: Describes whether the function can sleep, what locks it takes,
 *          releases, or expects to be held. It can extend over multiple
 *          lines.
 * Return: Describe the return value of function_name.
 *
 * The return value description can also have multiple paragraphs, and should
 * be placed at the end of the comment block.
 */

함수 이름 뒤의 짧은 설명은 여러 줄에 걸칠 수 있습니다. 인수 설명이 시작되거나 빈 주석 줄 또는 주석 블록의 끝을 만나면 짧은 설명이 끝납니다. 긴 설명은 빈 주석 줄 뒤에서 시작하며 여러 문단을 포함할 수 있습니다. `Context`와 `Return`은 정해진 의미를 갖는 절 이름이고, 반환값 설명은 주석 블록 끝에 두어야 합니다.

함수 매개변수 표기

각 함수 인수는 짧은 함수 설명 바로 다음에 선언 순서대로 설명합니다. 함수 설명과 인수 사이 또는 인수들 사이에 빈 줄을 두지 않습니다. 각 `@argument:` 설명은 여러 줄로 이어질 수 있습니다.

여러 줄 설명의 후속 줄은 앞 줄의 설명이 시작된 열에 맞춰야 합니다. 한 줄에서 설명을 시작하거나, 인수 이름 뒤를 비우고 다음 줄을 추가로 들여쓰는 두 형식을 사용할 수 있습니다.

   * @argument: some long description
   *            that continues on next lines

or::

   * @argument:
   *                some long description
   *                that continues on next lines

가변 인수 함수는 kernel-doc 표기 `@...:`를 사용하여 가변 인수를 설명합니다.

* @...: description

호출 문맥과 반환값

함수를 호출할 수 있는 문맥은 `Context` 절에 기술합니다. 함수가 sleep할 수 있는지, interrupt context에서 호출할 수 있는지, 어떤 lock을 획득하거나 해제하는지, 호출자가 어떤 lock을 보유해야 하는지를 포함해야 합니다.

* Context: Any context.
* Context: Any context. Takes and releases the RCU lock.
* Context: Any context. Expects <lock> to be held by caller.
* Context: Process context. May sleep if @gfp flags permit.
* Context: Process context. Takes and releases <mutex>.
* Context: Softirq or process context. Takes and releases <lock>, BH-safe.
* Context: Interrupt context.

반환값이 있다면 `Return` 또는 `Returns`라는 전용 절에서 설명합니다.

여러 줄 설명 텍스트는 단순한 줄바꿈을 보존하지 않습니다. 따라서 값을 줄마다 보기 좋게 적더라도 다음 예처럼 하나의 연속된 문장으로 합쳐집니다.

   * Return:
   * %0 - OK
   * %-EINVAL - invalid argument
   * %-ENOMEM - out of memory

this will all run together and produce::

   Return: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memory

원하는 줄 구분을 만들려면 ReST 목록을 사용해야 합니다.

* Return:
* * %0                - OK to runtime suspend the device
* * %-EBUSY        - Device should not be runtime suspended

또한 설명 줄이 어떤 구문과 콜론으로 시작하면 그 구문을 새로운 절 제목으로 인식합니다. 의도하지 않은 절이 생기지 않도록 반환값 설명의 문장 구조를 주의해야 합니다.

구조체·공용체·열거형 문서

`struct`, `union`, `enum`의 일반 형식은 타입 이름과 짧은 설명, `@member` 항목, 선택적인 긴 설명으로 구성합니다.

/**
 * struct struct_name - Brief description.
 * @member1: Description of member1.
 * @member2: Description of member2.
 *           One can provide multiple line descriptions
 *           for members.
 *
 * Description of the structure.
 */

공용체나 열거형을 설명할 때는 예제의 `struct`를 `union` 또는 `enum`으로 바꿉니다. 여기서 member는 구조체·공용체 멤버뿐 아니라 enum의 열거자도 뜻합니다. 타입 이름 뒤의 짧은 설명은 여러 줄일 수 있으며 멤버 설명, 빈 주석 줄, 블록 끝 중 하나에서 종료됩니다.

구조체, 공용체, 열거형의 멤버는 함수 매개변수와 같은 방식으로 문서화합니다. 짧은 설명 바로 뒤에 두며 여러 줄로 작성할 수 있습니다.

구조체나 공용체 설명 안에서는 `private:`와 `public:` 주석 태그를 사용할 수 있습니다. `private:` 영역의 필드는 생성된 출력 문서에 나타나지 않습니다. 두 태그는 `/*` 주석 표식 바로 뒤에서 시작해야 하며 콜론과 닫는 `*/` 사이에 선택적인 설명을 넣을 수 있습니다.

/**
 * struct my_struct - short description
 * @a: first member
 * @b: second member
 * @d: fourth member
 *
 * Longer description
 */
struct my_struct {
    int a;
    int b;
/* private: internal use only */
    int c;
/* public: the next one is public */
    int d;
};

중첩 구조체와 공용체

중첩 구조체와 공용체의 멤버는 바깥쪽 이름부터 점으로 연결한 경로로 문서화할 수 있습니다. 다음 예는 익명 중첩 타입의 멤버와 이름이 있는 `bar` 공용체 내부의 `st1`, `st2` 구조체 및 그 멤버를 모두 기술합니다.

/**
 * struct nested_foobar - a struct with nested unions and structs
 * @memb1: first member of anonymous union/anonymous struct
 * @memb2: second member of anonymous union/anonymous struct
 * @memb3: third member of anonymous union/anonymous struct
 * @memb4: fourth member of anonymous union/anonymous struct
 * @bar: non-anonymous union
 * @bar.st1: struct st1 inside @bar
 * @bar.st2: struct st2 inside @bar
 * @bar.st1.memb1: first member of struct st1 on union bar
 * @bar.st1.memb2: second member of struct st1 on union bar
 * @bar.st2.memb1: first member of struct st2 on union bar
 * @bar.st2.memb2: second member of struct st2 on union bar
 */
struct nested_foobar {
  /* Anonymous union/struct*/
  union {
    struct {
      int memb1;
      int memb2;
    };
    struct {
      void *memb3;
      int memb4;
    };
  };
  union {
    struct {
      int memb1;
      int memb2;
    } st1;
    struct {
      void *memb1;
      int memb2;
    } st2;
  } bar;
};

중첩 구조체 또는 공용체 `foo`에 이름이 있으면 그 안의 `bar` 멤버를 `@foo.bar:`로 문서화합니다. 중첩 구조체나 공용체가 익명이면 내부 `bar` 멤버를 단순히 `@bar:`로 문서화합니다.

인라인 멤버 문서 주석

구조체 멤버는 정의 내부에서 인라인으로도 문서화할 수 있습니다. 여는 `/**`와 닫는 `*/`가 같은 줄에 있는 한 줄 형식과, 다른 kernel-doc 주석처럼 두 표식이 각각 별도 줄에 있는 여러 줄 형식을 모두 지원합니다.

/**
 * struct foo - Brief description.
 * @foo: The Foo member.
 */
struct foo {
      int foo;
      /**
       * @bar: The Bar member.
       */
      int bar;
      /**
       * @baz: The Baz member.
       *
       * Here, the member description may contain several paragraphs.
       */
      int baz;
      union {
              /** @foobar: Single line description. */
              int foobar;
      };
      /** @bar2: Description for struct @bar2 inside @foo */
      struct {
              /**
               * @bar2.barbar: Description for @barbar inside @foo.bar2
               */
              int barbar;
      } bar2;
};

인라인 주석에서도 `@bar`, `@baz`, `@foobar`처럼 해당 멤버를 지목합니다. 중첩된 이름 있는 멤버는 `@bar2.barbar`처럼 전체 경로로 표시할 수 있고, 여러 줄 멤버 설명에는 여러 문단을 넣을 수 있습니다.

typedef 문서

일반 typedef는 `typedef type_name - 짧은 설명` 뒤에 빈 주석 줄과 타입의 긴 설명을 둡니다.

/**
 * typedef type_name - Brief description.
 *
 * Description of the type.
 */

함수 prototype을 담은 typedef도 문서화할 수 있습니다. 함수처럼 인수를 나열하고 긴 설명, `Context`, `Returns`를 추가한 뒤 실제 함수 포인터 typedef 선언을 배치합니다.

/**
 * typedef type_name - Brief description.
 * @arg1: description of arg1
 * @arg2: description of arg2
 *
 * Description of the type.
 *
 * Context: Locking context.
 * Returns: Meaning of the return value.
 */
 typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2);

객체형 매크로 문서

객체형 매크로는 함수형 매크로와 구분됩니다. 매크로 이름 바로 뒤에 왼쪽 괄호 `(`가 있으면 함수형이고, 괄호가 없으면 객체형입니다. `scripts/kernel-doc`는 함수형 매크로를 매개변수 목록을 가질 수 있는 함수처럼 처리하지만 객체형 매크로에는 매개변수 목록이 없습니다.

객체형 매크로의 일반 형식은 `define object_name - 짧은 설명`과 선택적인 긴 설명입니다.

/**
 * define object_name - Brief description.
 *
 * Description of the object.
 */

`MAX_ERRNO` 예제는 지원하는 최대 errno 값과, 커널 포인터의 중복 정보를 이용해 오류 코드와 정상 포인터를 같은 반환값 형식으로 전달하는 이유를 설명합니다.

/**
 * define MAX_ERRNO - maximum errno value that is supported
 *
 * Kernel pointers have redundant information, so we can use a
 * scheme where we can return either an error code or a normal
 * pointer with the same return value.
 */
#define MAX_ERRNO        4095

여러 줄 매크로도 같은 방식으로 문서화합니다. `DRM_GEM_VRAM_PLANE_HELPER_FUNCS` 예제는 VRAM 처리용 `drm_plane_helper_funcs`를 각 helper 함수로 초기화하는 매크로를 설명합니다.

/**
 * define DRM_GEM_VRAM_PLANE_HELPER_FUNCS - \
 *        Initializes struct drm_plane_helper_funcs for VRAM handling
 *
 * This macro initializes struct drm_plane_helper_funcs to use the
 * respective helper functions.
 */
#define DRM_GEM_VRAM_PLANE_HELPER_FUNCS \
      .prepare_fb = drm_gem_vram_plane_helper_prepare_fb, \
      .cleanup_fb = drm_gem_vram_plane_helper_cleanup_fb

강조 표기와 교차 참조

kernel-doc 주석의 설명 텍스트에서는 다음 특수 패턴을 인식해 적절한 reStructuredText 마크업과 `Sphinx C Domain` 참조로 변환합니다. 이 표기는 일반 reStructuredText 문서에서는 인식되지 않고 kernel-doc 주석 안에서만 동작합니다.

• `funcname()`은 함수 참조입니다.
• `@parameter`는 함수 매개변수 이름이며 교차 참조 없이 서식만 적용합니다.
• `%CONST`는 상수 이름이며 교차 참조 없이 서식만 적용합니다.
• 이중 backtick 자체를 포함한 ````literal```` 표기는 내용을 그대로 처리하는 literal입니다. 출력은 `monospaced font`를 사용하며 kernel-doc 또는 reStructuredText에서 특별한 의미를 갖는 문자를 안전하게 적을 때 유용합니다. 함수 설명 안의 `%ph` 같은 표기에 특히 유용합니다.
• `$ENVVAR`는 환경 변수 이름이며 교차 참조 없이 서식만 적용합니다.
• `&struct name`, `&enum name`, `&typedef name`은 각각 구조체, enum, typedef 참조입니다.
• `&struct_name->member` 또는 `&struct_name.member`는 구조체·공용체 멤버 참조입니다. 링크 대상은 멤버 자체가 아니라 구조체나 공용체 정의입니다.
• `&name`은 일반 타입 참조입니다. 주로 오래된 주석을 위한 표기이므로 가능하면 앞에서 설명한 완전한 참조 형식을 사용합니다.

reStructuredText에서 교차 참조하기

reStructuredText 문서에서 kernel-doc 주석에 정의된 함수와 타입을 참조할 때 추가 구문은 필요하지 않습니다. 함수 이름은 `()`로 끝내고 타입 이름 앞에는 `struct`, `union`, `enum`, `typedef` 중 알맞은 키워드를 씁니다.

See foo().
See struct foo.
See union bar.
See enum baz.
See typedef meh.

교차 참조 링크에 사용자 정의 표시 텍스트가 필요하면 Sphinx C Domain의 `:c:func:` 또는 `:c:type:` 역할을 사용합니다.

See :c:func:`my custom link text for function foo <foo>`.
See :c:type:`my custom link text for struct bar <bar>`.

세부 규칙은 앞에서 연결한 `Sphinx C Domain` 문서를 참고합니다.

개요 문서 주석

소스 코드와 설명을 가까이 두기 위해 함수, 구조체, 공용체, enum, typedef에 속하지 않는 자유 형식 kernel-doc 블록을 포함할 수 있습니다. 예를 들어 driver 또는 library code의 동작 원리를 설명하는 데 사용할 수 있습니다.

이 형식은 절 제목과 함께 `DOC:` 절 키워드를 사용합니다.

/**
 * DOC: Theory of Operation
 *
 * The whizbang foobar is a dilly of a gizmo. It can do whatever you
 * want it to do, at any time. It reads your mind. Here's how it works.
 *
 * foo bar splat
 *
 * The only drawback to this gizmo is that is can sometimes damage
 * hardware, software, or its subject(s).
 */

`DOC:` 뒤의 제목은 소스 파일 안에서 heading 역할을 하는 동시에 문서 주석을 추출하는 식별자 역할도 합니다. 따라서 제목은 해당 파일 안에서 고유해야 합니다.

kernel-doc 주석 포함과 export 옵션

전용 kernel-doc Sphinx directive 확장을 사용하면 어느 reStructuredText 문서에서든 소스의 문서 주석을 포함할 수 있습니다.

.. kernel-doc:: source
   :option:

`source`는 커널 소스 트리를 기준으로 한 소스 파일 경로입니다. directive의 `export` 옵션은 `source` 또는 `source-pattern`과 일치하는 파일에서 `EXPORT_SYMBOL`이나 `EXPORT_SYMBOL_GPL`로 내보낸 모든 함수의 문서를 포함합니다.

`source-pattern`은 kernel-doc 주석은 헤더 파일에 있고 `EXPORT_SYMBOL` 또는 `EXPORT_SYMBOL_GPL`은 함수 정의 옆의 구현 파일에 있을 때 유용합니다.

.. kernel-doc:: lib/bitmap.c
   :export:

.. kernel-doc:: include/net/mac80211.h
   :export: net/mac80211/*.c

kernel-doc directive 옵션

`internal` 옵션은 `source`와 선택적인 `source-pattern` 파일에서 `EXPORT_SYMBOL` 또는 `EXPORT_SYMBOL_GPL`로 내보내지 않은 모든 함수와 타입의 문서를 포함합니다.

.. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
   :internal:

`identifiers` 옵션은 `source`에서 지정한 각 함수와 타입의 문서를 포함합니다. 함수를 하나도 지정하지 않으면 소스의 모든 함수와 타입을 포함합니다. 타입에는 struct, union, enum, typedef 식별자를 지정할 수 있습니다.

.. kernel-doc:: lib/bitmap.c
   :identifiers: bitmap_parselist bitmap_parselist_user

.. kernel-doc:: lib/idr.c
   :identifiers:

`no-identifiers` 옵션은 지정한 각 함수와 타입의 문서를 제외합니다.

.. kernel-doc:: lib/bitmap.c
   :no-identifiers: bitmap_parselist

`functions`는 `identifiers` directive의 오래된 별칭이며 deprecated 상태입니다.

`doc` 옵션은 `source`에서 지정한 제목의 `DOC:` 문단을 포함합니다. 제목에는 공백을 사용할 수 있지만 따옴표로 감싸지 않습니다. 제목은 문단 식별자로만 쓰이고 출력에는 나타나지 않으므로, 이를 감싸는 reStructuredText 문서에 적절한 heading을 따로 마련해야 합니다.

.. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
   :doc: High Definition Audio over HDMI and Display Port

옵션을 지정하지 않으면 kernel-doc directive는 소스 파일의 모든 문서 주석을 포함합니다. 확장은 커널 트리의 `Documentation/sphinx/kerneldoc.py`에 있으며 내부적으로 `scripts/kernel-doc` 스크립트를 호출해 문서 주석을 추출합니다.

kernel-doc으로 man page 생성하기

커널 git tree에서 kernel-doc으로 man page만 생성하려면 `/**`를 포함하는 파일을 찾되 `Documentation`과 `tools` 경로를 제외하고, `scripts/kernel-doc -man`의 출력을 `scripts/split-man.pl /tmp/man`으로 전달합니다.

$ scripts/kernel-doc -man \
  $(git grep -l '/\*\*' -- :^Documentation :^tools) \
  | scripts/split-man.pl /tmp/man

오래된 git 버전 중 일부는 특정 path exclusion 구문을 지원하지 않습니다. 그런 버전에서는 `:!경로` 표기 또는 `:(exclude)경로` 표기를 사용하는 다음 명령 중 하나를 사용할 수 있습니다.

$ scripts/kernel-doc -man \
  $(git grep -l '/\*\*' -- . ':!Documentation' ':!tools') \
  | scripts/split-man.pl /tmp/man

$ scripts/kernel-doc -man \
  $(git grep -l '/\*\*' -- . ":(exclude)Documentation" ":(exclude)tools") \
  | scripts/split-man.pl /tmp/man