docs: api/cacge move grn_cache_open() reference to the header file

GitHub: groongaGH-1817

Prepare to switch to documents automatically generated by Doxygen.

doc/locale/ja/LC_MESSAGES/reference/api/grn_cache.po

@@ -54,21 +54,12 @@ msgstr "リファレンス"
 msgid "It is an opaque cache object. You can create a ``grn_cache`` by :c:func:`grn_cache_open()` and free the created object by :c:func:`grn_cache_close()`."
 msgstr "``grn_cache`` は詳細を公開していないオブジェクトです。 :c:func:`grn_cache_open()` で作成し、 :c:func:`grn_cache_close()` で解放できます。"
 
-msgid "Creates a new cache object."
-msgstr "新規にキャッシュオブジェクトを作成します。"
-
-msgid "If memory allocation for the new cache object is failed, ``NULL`` is returned. Error information is stored into the ``ctx``."
-msgstr "新しいキャッシュオブジェクト作成のためのメモリ割り当てに失敗した場合、 ``NULL`` を返します。エラー情報は ``ctx`` に格納されます。"
+msgid "Frees resourses of the ``cache``."
+msgstr "``cache`` のリソースを解放。"
 
 msgid "The context."
 msgstr "その時点のコンテキスト。"
 
-msgid "A newly allocated cache object on success, ``NULL`` otherwise. The returned cache object must be freed by :c:func:`grn_cache_close()`."
-msgstr "新しいキャッシュオブジェクトの作成に成功した場合は ``NULL`` 以外の値を返します。このキャッシュオブジェクトは :c:func:`grn_cache_close()` で解放されなければなりません。"
-
-msgid "Frees resourses of the ``cache``."
-msgstr "``cache`` のリソースを解放。"
-
 msgid "The cache object to be freed."
 msgstr "キャッシュオブジェクトを解放する。"
 

doc/source/reference/api/grn_cache.rst

@@ -57,18 +57,6 @@ Reference
    :c:func:`grn_cache_open()` and free the created object by
    :c:func:`grn_cache_close()`.
 
-.. c:function:: grn_cache *grn_cache_open(grn_ctx *ctx)
-
-   Creates a new cache object.
-
-   If memory allocation for the new cache object is failed, ``NULL``
-   is returned. Error information is stored into the ``ctx``.
-
-   :param ctx: The context.
-   :return: A newly allocated cache object on success, ``NULL``
-            otherwise. The returned cache object must be freed by
-            :c:func:`grn_cache_close()`.
-
 .. c:function:: grn_rc grn_cache_close(grn_ctx *ctx, grn_cache *cache)
 
    Frees resourses of the ``cache``.

include/groonga/cache.h

@@ -28,6 +28,52 @@ typedef struct _grn_cache grn_cache;
 GRN_API void grn_set_default_cache_base_path(const char *base_path);
 GRN_API const char *grn_get_default_cache_base_path(void);
 
+/**
+ * \brief Create a new cache object.
+ *
+ * Initializes a cache based on the current configuration or environment
+ * settings. The cache operates in either memory mode or persistent mode.
+ *
+ * **Cache Modes**:
+ *
+ * Memory Cache:
+ * - Each worker has an independent cache.
+ * - Suitable for single-worker setups.
+ *
+ * Persistent Cache:
+ * - Multiple workers share the same cache for `groonga-nginx` setups.
+ * - Slightly slower than memory cache due to filesystem I/O.
+ *
+ * **Cache Mode Configuration**:
+ *
+ * Cache mode can be configured in three ways:
+ *
+ * **Default Configuration**:
+ * - By default, `groonga_cache_base_path` is set to `off`, enabling memory-only
+ *   caching, which is used in `groonga-nginx` settings.
+ * - To use persistent caching, set `groonga_cache_base_path` to a valid path
+ *   (preferably on a memory file system like `/dev/shm`).
+ *
+ * **Environment Variable**:
+ *
+ * If `groonga_cache_base_path` is not set, the function checks the
+ * `GRN_CACHE_TYPE` environment variable.
+ * - If `GRN_CACHE_TYPE` is set to `persistent`, it enables persistent cache
+ *   mode without a specified base path.
+ * - If `GRN_CACHE_TYPE` is set to any other value or is unset, it uses
+ *   memory-only cache mode.
+ *
+ * **C API**:
+ *
+ * Use \ref grn_set_default_cache_base_path to override the configuration or
+ * environment settings at runtime.
+ *
+ * \param ctx The context object used for memory allocation and error handling.
+ *
+ * \return A newly created \ref grn_cache object on success, NULL on error. The
+ *         returned \ref grn_cache object must be freed by \ref grn_cache_close.
+ *         See ctx->rc for error details.
+ */
 GRN_API grn_cache *grn_cache_open(grn_ctx *ctx);
 GRN_API grn_cache *grn_persistent_cache_open(grn_ctx *ctx,
                                              const char *base_path);