docs api/grn_obj: move the grn_obj_column() reference to the header f…

…ile (groonga#1863) GitHub: ref groongaGH-1817 Prepare to switch to documents automatically generated by Doxygen. --------- Co-authored-by: Abe Tomoaki <[email protected]>
otegami · Aug 14, 2024 · 7d5ae0a · 7d5ae0a
1 parent 8df9668
commit 7d5ae0a
Show file tree

Hide file tree

Showing 3 changed files with 36 additions and 20 deletions.
diff --git a/doc/locale/ja/LC_MESSAGES/reference/api/grn_obj.po b/doc/locale/ja/LC_MESSAGES/reference/api/grn_obj.po
@@ -36,17 +36,8 @@ msgstr "例"
 msgid "Reference"
 msgstr "リファレンス"
 
-msgid "nameがカラム名の場合、それに対応するtableのカラムを返します。対応するカラムが存在しなければNULLを返します。"
-msgstr ""
-
-msgid "nameがアクセサ文字列の場合、それに対応するaccessorを返します。アクセサ文字列とは、カラム名等を'.'で連結した文字列です。'_id', '_key'は特殊なアクセサで、それぞれレコードID/keyを返します。例) 'col1' / 'col2.col3' / 'col2._id'"
-msgstr ""
-
-msgid "対象tableを指定します。"
-msgstr ""
-
-msgid "カラム名を指定します。"
-msgstr ""
+msgid "We are currently switching to automatic generation using Doxygen."
+msgstr "現在、Doxygenを使った自動生成に切り替え中です。"
 
 msgid "Check whether Groonga built-in object."
 msgstr ""

diff --git a/doc/source/reference/api/grn_obj.rst b/doc/source/reference/api/grn_obj.rst
@@ -16,19 +16,13 @@ TODO...
 Reference
 ---------
 
+.. note::
+   We are currently switching to automatic generation using Doxygen.
+
 .. c:type:: grn_obj
 
    TODO...
 
-.. c:function:: grn_obj *grn_obj_column(grn_ctx *ctx, grn_obj *table, const char *name, unsigned int name_size)
-
-   nameがカラム名の場合、それに対応するtableのカラムを返します。対応するカラムが存在しなければNULLを返します。
-
-   nameがアクセサ文字列の場合、それに対応するaccessorを返します。アクセサ文字列とは、カラム名等を'.'で連結した文字列です。'_id', '_key'は特殊なアクセサで、それぞれレコードID/keyを返します。例) 'col1' / 'col2.col3' / 'col2._id'
-
-   :param table: 対象tableを指定します。
-   :param name: カラム名を指定します。
-
 .. c:function:: grn_bool grn_obj_is_builtin(grn_ctx *ctx, grn_obj *obj)
 
    Check whether Groonga built-in object.

diff --git a/include/groonga/groonga.h b/include/groonga/groonga.h
@@ -720,6 +720,37 @@ typedef enum {
   GRN_OP_ORDERED_NEAR_PHRASE_PRODUCT,
 } grn_operator;
 
+/**
+ * \brief Retrieve a column or an accessor from a specified table or accessor.
+ *
+ *        This function returns a column corresponding to the given name from
+ *        the specified table. If the name does not correspond to any column, it
+ *        returns NULL. If the name is an accessor string, it returns the
+ *        corresponding accessor. Accessor strings are dot-concatenated column
+ *        names. Column names that are started with `_` such as `_id` and `_key`
+ *        are pseudo column names. This function returns an accessor for a
+ *        pseudo column name.
+ *        See https://groonga.org/docs/reference/columns/pseudo.html for pseudo
+ *        column.
+ *
+ *        Column name examples: `name`, `age`
+ *
+ *        Pseudo column name examples: `_key`, `_score`, `_nsubrecs`
+ *
+ *        Accessor string examples: `tag.name`, `user.bookmarks.url`
+ *
+ *        If this function returns an accessor, you must call `grn_obj_unlink()`
+ *        with it when it's no longer needed. You can use
+ *        `grn_obj_is_accessor()` to detect whether it's an accessor or not.
+ *
+ * \param ctx The context object
+ * \param table The target table or accessor from which the column or accessor
+ *              is retrieved.
+ * \param name The name of the column or an accessor string.
+ * \param name_size The length of the `name` string.
+ *
+ * \return The column or accessor, or NULL if not found.
+ */
 GRN_API grn_obj *
 grn_obj_column(grn_ctx *ctx,
                grn_obj *table,