From 891ae3947a1b04c514efc640b0a3c4ab46fe9e21 Mon Sep 17 00:00:00 2001
From: Abe Tomoaki <abe@clear-code.com>
Date: Wed, 31 Jul 2024 16:36:37 +0900
Subject: [PATCH] docs: api/grn_table: Move the grn_table_add() reference to
 the header file (#1838)

GitHub: GH-1817

Prepare to switch to documents automatically generated by Doxygen.
---
 doc/source/reference/api/grn_table.rst | 10 ----------
 include/groonga/table.h                | 18 ++++++++++++++++--
 2 files changed, 16 insertions(+), 12 deletions(-)

diff --git a/doc/source/reference/api/grn_table.rst b/doc/source/reference/api/grn_table.rst
index 495b270682..d10d2c0b56 100644
--- a/doc/source/reference/api/grn_table.rst
+++ b/doc/source/reference/api/grn_table.rst
@@ -16,16 +16,6 @@ TODO...
 Reference
 ---------
 
-.. c:function:: grn_id grn_table_add(grn_ctx *ctx, grn_obj *table, const void *key, unsigned int key_size, int *added)
-
-   keyに対応する新しいrecordをtableに追加し、そのIDを返します。keyに対応するrecordがすでにtableに存在するならば、そのrecordのIDを返します。
-
-   ``GRN_OBJ_TABLE_NO_KEY`` が指定されたtableでは、key, key_size は無視されます。
-
-   :param table: 対象tableを指定します。
-   :param key: 検索keyを指定します。
-   :param added: NULL以外の値が指定された場合、新たにrecordが追加された時には1が、既存recordだった時には0がセットされます。
-
 .. c:function:: grn_id grn_table_get(grn_ctx *ctx, grn_obj *table, const void *key, unsigned int key_size)
 
    It finds a record that has key parameter and returns ID of the found record. If table parameter is a database, it finds an object (table, column and so on) that has key parameter  and returns ID of the found object.
diff --git a/include/groonga/table.h b/include/groonga/table.h
index 37a7e535f6..b7ee6fa798 100644
--- a/include/groonga/table.h
+++ b/include/groonga/table.h
@@ -84,8 +84,22 @@ grn_table_create_similar(grn_ctx *ctx,
                                (flags),                                        \
                                (key_type),                                     \
                                (value_type))))
-
-/* TODO: int *added -> bool *added */
+/**
+ * \brief Add a new record with `key` to the table and return its ID.
+ *        If `key` already exists in the table, returns the ID of the record.
+ *        For tables with GRN_OBJ_TABLE_NO_KEY, `key` and `key_size` are ignored
+ *
+ * \param ctx The context object
+ * \param table Target table
+ * \param key Search key
+ * \param key_size Length of `key`
+ * \param added If a non `NULL` value is specified, 1 is set when a new record
+ *              is added, and 0 is set when it is an existing record
+ *
+ * \return Record ID on success, GRN_ID_NIL on error
+ *
+ * \todo int *added -> bool *added
+ */
 GRN_API grn_id
 grn_table_add(grn_ctx *ctx,
               grn_obj *table,