문서 업데이트

4 files changed, 98 insertions, 2 deletions

diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in
index 31638e3..1fdd062 100644
--- a/doc/Doxyfile.in
+++ b/doc/Doxyfile.in
@@ -453,6 +453,7 @@ WARN_LOGFILE           =
 INPUT                  = ../hangul/hangul.h \
 			 ../hangul/hangulctype.c \
 			 ../hangul/hangulinputcontext.c \
+			 ../hangul/hangulkeyboard.c \
 			 ../hangul/hanja.c \
 			 mainpage.dox \
 			 hangulkeyboards.dox
diff --git a/doc/gen_hangulkeyboards.py b/doc/gen_hangulkeyboards.py
index 764f14f..4176c81 100755
--- a/doc/gen_hangulkeyboards.py
+++ b/doc/gen_hangulkeyboards.py
@@ -286,7 +286,8 @@ print '''/**
 
 @defgroup hangulkeyboards 한글 자판
 
-libhangul에서 builtin으로 지원하는 자판은 @ref layout_2, @ref layout_2y,
+@section supportkeyboards libhangul이 지원하는 한글 자판
+libhangul에서 지원하는 자판은 @ref layout_2, @ref layout_2y,
 @ref layout_3f, @ref layout_390, @ref layout_3s,
 @ref layout_3y, @ref layout_ahn, @ref layout_ro 자판 이다.
 
diff --git a/hangul/hangulinputcontext.c b/hangul/hangulinputcontext.c
index 504d507..d8d93f6 100644
--- a/hangul/hangulinputcontext.c
+++ b/hangul/hangulinputcontext.c
@@ -1310,6 +1310,15 @@ hangul_ic_has_jongseong(HangulInputContext *hic)
     return hangul_buffer_has_jongseong(&hic->buffer);
 }
 
+/**
+ * @ingroup hangulic
+ * @brief @ref HangulInputContext 의 조합 옵션을 확인하는 함수
+ * @param hic @ref HangulInputContext 를 가리키는 포인터
+ * @param option @ref HangulInputContext 의 조합 처리 옵션.
+ *        @ref hangul_ic_set_option 에서 사용 가능한 옵션을 확인하라.
+ *
+ * @return @ref HangulInputContext 에 설정된 옵션값을 리턴한다.
+ */
 bool
 hangul_ic_get_option(HangulInputContext* hic, int option)
 {
@@ -1325,6 +1334,28 @@ hangul_ic_get_option(HangulInputContext* hic, int option)
     return false;
 }
 
+/**
+ * @ingroup hangulic
+ * @brief @ref HangulInputContext 의 조합 옵션을 설정하는 함수
+ * @param hic @ref HangulInputContext 를 가리키는 포인터
+ * @param option @ref HangulInputContext 의 조합 처리 옵션.
+ *               아래와 같은 옵션이 선택 가능하다.
+ *    - HANGUL_IC_OPTION_AUTO_REORDER
+ *      - 자동 순서 교정 옵션. 모아치기를 위해서는 켜야 한다.
+ *        예) true면 ㅏ+ㄱ -> 가 로 완성시켜 줌.
+ *    - HANGUL_IC_OPTION_COMBI_ON_DOUBLE_STROKE
+ *      - 두벌식 자판에서 자음 연타로 된소리로 조합하는 옵션.
+ *        원래 자판이 자음 연타로 동작하는 세벌식이나 옛한글
+ *        자판에서는 옵션이 동작하지 않는다.
+ *        MS IME와 호환을 위해서 사용.
+ *        예) true면 ㄱ+ㄱ -> ㄲ 으로 조합시켜 줌.
+ *    - HANGUL_IC_OPTION_NON_CHOSEONG_COMBI
+ *      - 두벌식 자판에서 초성에 없는 겹자음을 조합허용하는 옵션.
+ *        두벌식 자판 이외에는 옵션이 동작하지 않는다.
+ *        MS IME와 호환을 위해서 사용.
+ *        예) true면 ㄱ+ㅅ -> ㄳ 으로 조합시켜 줌.
+ * @param value 설정하고자 하는 값, true 또는 false
+ */
 void
 hangul_ic_set_option(HangulInputContext* hic, int option, bool value)
 {
@@ -1506,18 +1537,21 @@ hangul_ic_delete(HangulInputContext *hic)
     free(hic);
 }
 
+/** @deprecated 이 함수 대신 @ref hangul_keyboard_list_get_count 를 사용하라 */
 unsigned int
 hangul_ic_get_n_keyboards()
 {
     return hangul_keyboard_list_get_count();
 }
 
+/** @deprecated 이 함수 대신 @ref hangul_keyboard_list_get_keyboard_id 를 사용하라 */
 const char*
 hangul_ic_get_keyboard_id(unsigned index_)
 {
     return hangul_keyboard_list_get_keyboard_id(index_);
 }
 
+/** @deprecated 이 함수 대신 @ref hangul_keyboard_list_get_keyboard_name 을 사용하라 */
 const char*
 hangul_ic_get_keyboard_name(unsigned index_)
 {
@@ -1551,6 +1585,12 @@ hangul_ic_is_transliteration(HangulInputContext *hic)
     return false;
 }
 
+/**
+ * @ingroup hangulic
+ * @breif libhangul을 초기화 하는 함수.
+ *
+ * libhangul의 함수를 사용하기 전에 호출해야 한다.
+ */
 int
 hangul_init()
 {
@@ -1559,6 +1599,12 @@ hangul_init()
     return res;
 }
 
+/**
+ * @ingroup hangulic
+ * @breif libhangul에서 사용한 리소스를 해제하는 함수.
+ *
+ * libhangul의 함수의 사용이 끝나면 호출해야 한다.
+ */
 int
 hangul_fini()
 {
diff --git a/hangul/hangulkeyboard.c b/hangul/hangulkeyboard.c
index 168774a..0d919cb 100644
--- a/hangul/hangulkeyboard.c
+++ b/hangul/hangulkeyboard.c
@@ -33,6 +33,27 @@
 #include "hangul.h"
 #include "hangulinternals.h"
 
+/**
+ * @file hangulkeyboard.c
+ */
+
+/**
+ * @addtogroup hangulkeyboards
+ *
+ * @section addinghangulkeyboards 한글 키보드 추가 방법
+ * libhangul이 한글 키보드 파일을 읽는 위치는 두 곳이다.
+ *  - @$(pkgdatadir)/keyboards 디렉토리에 설치된 파일은 전역 시스템에서
+ *    인식한다.
+ *  - @$HOME/.local/share/libhangul/keyboards 또는 @$XDG_DATA_HOME/libhangul/keyboards
+ *    디렉토리에 설치된 파일은 개별 사용자만 인식한다.
+ *
+ * 키보드 파일의 로딩 순서는 시스템 파일을 먼저 로딩하고 사용자 파일을
+ * 로딩한다. 따라서 한글 키보드 목록을 이터레이션하면 사용자 추가 자판은
+ * 마지막에 나오게 된다. 사용자 자판 선택 알고리듬이 처음 나온 자판을
+ * 인식하는 방식이므로 동일한 id를 가진 자판을 등록하면 먼저 등록된 자판만
+ * 인식되므로 주의가 필요하다. 다시 말해서 시스템 자판과 같은 id를 가진
+ * 자판은 등록하여 사용할 수 없다.
+ */
 
 #define LIBHANGUL_KEYBOARD_DIR LIBHANGUL_DATA_DIR "/keyboards"
 //#define LIBHANGUL_KEYBOARD_DIR TOP_SRCDIR "/data/keyboards"
@@ -207,7 +228,6 @@ typedef struct _HangulKeyboardLoadContext {
 static void    hangul_keyboard_parse_file(const char* path, void* user_data);
 static bool    hangul_keyboard_list_append(HangulKeyboard* keyboard);
 
-
 HangulCombination*
 hangul_combination_new()
 {
@@ -865,6 +885,14 @@ hangul_builtin_keyboard_list_get_keyboard(const char* id)
     return NULL;
 }
 
+/**
+ * @ingroup hangulkeyboards
+ * @brief libhangul에서 제공하는 자판 개수를 구하는 함수
+ *
+ * 이 함수의 리턴값을 이용해서 자판을 iteration할 수 있다.
+ * 한글 자판의 설치 위치에 대한 정보는 @ref addinghangulkeyboards 를 참고하라.
+ * @return @ref HangulInputContext 에서 선택 가능한 자판 개수
+ */
 unsigned int
 hangul_keyboard_list_get_count()
 {
@@ -874,6 +902,15 @@ hangul_keyboard_list_get_count()
     return hangul_keyboards.n;
 }
 
+/**
+ * @ingroup hangulkeyboards
+ * @brief libhangul에서 제공하는 자판의 id를 구하는 함수
+ *
+ * @a index_ 로 지정된 자판의 id 값을 리턴한다. 이 id는 @ref
+ * hangul_ic_select_keyboard() 함수의 인자로 사용하는 문자열이다.
+ * @return 지정된 자판의 id. 이 문자열은 libhangul 내부에서 관리하는 것으로
+ *         free해서는 안된다.
+ */
 const char*
 hangul_keyboard_list_get_keyboard_id(unsigned index_)
 {
@@ -891,6 +928,15 @@ hangul_keyboard_list_get_keyboard_id(unsigned index_)
     return keyboard->id;
 }
 
+/**
+ * @ingroup hangulkeyboards
+ * @brief libhangul에서 제공하는 자판의 이름을 구하는 함수
+ *
+ * @a index_ 로 지정된 자판의 이름을 리턴한다. 이 문자열은 사용자에게 보여주기
+ * 위한 것으로, 번역되어 사람이 읽을 수 있는 형태의 문자열이다.
+ * @return 지정된 자판의 이름. 이 문자열은 libhangul 내부에서 관리하는 것으로
+ *         free해서는 안된다.
+ */
 const char*
 hangul_keyboard_list_get_keyboard_name(unsigned index_)
 {
@@ -915,6 +961,8 @@ hangul_keyboard_list_get_keyboard(const char* id)
 	return hangul_builtin_keyboard_list_get_keyboard(id);
     }
 
+    /* 키보드 목록에서 순차 검색을 하여 찾으므로 같은 id로 서로다른
+     * 자판이 등록되어 있다고 하면 먼저 로딩된 자판만 인식된다. */
     size_t i;
     for (i = 0; i < hangul_keyboards.n; ++i) {
 	HangulKeyboard* keyboard = hangul_keyboards.keyboards[i];