/**
 *  @brief          Sets the position.
 *  @param[in]      x,y,z Coordinates of the position in 3D space.
 */
void setPosition(double x, double y, double z);

/**
 *  @brief          Pretty nice method.
 *  @details        This method is used to demonstrate a number of section commands.
 *  @author         John Doe
 *  @author         Jan Doe
 *  @version        4.1a
 *  @date           1990-2011
 *  @pre            First initialize the system.
 *  @bug            Not all memory is freed when deleting an object of this method.
 *  @warning        Improper use can crash your application.
 *  @copyright      GNU Public License.
 */
void SomeNiceMethod ();

/**
 *  @defgroup       MenuTests "Menu Testing Procedures"
 *  @brief          Manual testing procedures for menu functionality.
 */

/**
 *  @test           Menu item selection test.
 *                  1. Open the application menu.
 *                  2. Click on "File" menu item.
 *                  3. Verify submenu appears.
 *                  4. Select "New Document" option.
 *                  5. Confirm new document is created.
 */
void testMenuSelection();

/**
 *  @todo           Todo リストを記載します。この行はリスト名となります (省略可能)。
 *                  - 子リスト1
 *                  - 子リスト2
 *                  - 子リスト3
 */

/**
 *  @brief          Some description.
 *  @param[in]      grid1 First grid.
 *  @param[in]      grid2 Second grid.
 *  @pre            @p grid1 and @p grid2 must be of the same dimensions.
 */

/**
 *  @brief          Trim leading and trailing whitespace from a string.
 *  @param[in,out]  str string to prune.
 *  @pre            @p str is non-empty.
 */
inline void trim(char *str) {
    // If the string is empty, do nothing
    // ...
}

/**
 *  @brief          配列をソートします。
 * 
 *  @param[in,out]  arr ソート対象の配列を表します。
 *  @param[in]      size 配列のサイズを表します。
 * 
 *  @post           @p arr contains the same elements as before, but in sorted order.
 *  @post           arr[i] <= arr[i+1] for all valid i (0 <= i < size-1).
 *  @post           The original elements are preserved (no elements added or removed).
 */
void sortArray(int *arr, size_t size);

/**
 *  @par            History
 *                  - yyyy/mm/dd [修正ID](https://example.com/id/1234) 修正の概要を記載します。
 *                      - 子リスト1
 *                      - 子リスト2
 *                  - yyyy/mm/dd [修正ID](https://example.com/id/5678) 修正の概要を記載します。
 *                      - 子リスト1
 *                        子リスト1の続き
 */

/**
 *  @par            スレッド セーフティ
 *  本関数はスレッドセーフです。\n
 *  内部でミューテックスを使用しているため、複数スレッドから並行して呼び出せます。
 *
 *  @warning        引数が NULL の場合は失敗を返します。
 */

/**
 *  @par            スレッド セーフティ
 *  本関数はスレッドセーフではありません。\n
 *  同一ハンドルへの並行呼び出しは未定義動作です。\n
 *  呼び出しは 1 スレッドから行ってください。
 *
 *  @warning        handle が NULL の場合は失敗を返します。
 */

/**
 *******************************************************************************
 *  @file           compiler.h
 *  @brief          コンパイラ検出マクロのヘッダーファイル。
 *
 *  @section        compiler_detection コンパイラ検出マクロ
 *
 *  検出されたコンパイラに応じて、以下のマクロを定義します。
 *
 *  | コンパイラ | 識別マクロ    | COMPILER_NAME |
 *  | ---------- | ------------- | ------------- |
 *  | MSVC       | COMPILER_MSVC | "MSVC"        |
 *  | GCC        | COMPILER_GCC  | "GCC"         |
 *  | Clang      | COMPILER_CLANG| "Clang"       |
 *
 *  @section        inline_control インライン制御マクロ
 *
 *  コンパイラ固有のインライン属性を抽象化します。
 *
 *  使用例:
 *
    @code{.c}
    FORCE_INLINE int fast_add(int a, int b) { return a + b; }
    @endcode
 *
 *******************************************************************************
 */

/**
 *  @section        platform プラットフォーム検出
 *
 *  @subsection     platform_os OS 検出マクロ
 *
 *  OS を検出して識別マクロを定義します。
 *
 *  @subsection     platform_arch アーキテクチャ検出マクロ
 *
 *  CPU アーキテクチャを検出して識別マクロを定義します。
 */

/**
 *  @copyright Copyright (C) CompanyName, Ltd. 2025. All rights reserved.
 */

/**
 *  @copyright Copyright (C) CompanyName, Ltd. 2023-2025. All rights reserved.
 */

/**
 *  @brief          2 つの整数を除算します。
 *  @param[in]      a 被除数。
 *  @param[in]      b 除数。
 *  @return         除算結果。
 *  @details        PlantUML の図を挿入することができます。
    @startuml
        caption 図のテスト
        circle a
        circle b
        rectangle "a/b" as devide
        circle return
        a -> devide : 被除数
        b -> devide : 除数
        devide -> return
    @enduml
 *  @warning        @p b が 0 の場合、結果は未定義です。
 */
double divide(int a, int b);

/**
 *******************************************************************************
 *  @brief          プログラムのエントリーポイント。
 *  @param[in]      argc コマンドライン引数の数。
 *  @param[in]      argv コマンドライン引数の配列。
 *  @return         成功時は 0、失敗時は 0 以外の値を返します。
 *
 *  @details        以下に、calc コマンドの処理フローを示します。
 *
 *  @image          html calc-flow.png "calc コマンドの処理フロー"
 *
 *  @attention      引数は正確に 3 つ必要です。
 *******************************************************************************
 */
int main(int argc, char *argv[]);

/**
 *  @brief          文字列を反転します。
 *  @param[in,out]  str 反転する文字列。
 *  @details        以下は使用例です。
    @code{.c}
    char text[] = "Hello";
    reverseString(text);
    printf("%s\n", text);  // 出力: olleH
    @endcode
 */
void reverseString(char *str);

/**
 *  @brief          配列の最大値を取得します。
 *  @param[in]      arr 配列。
 *  @param[in]      size 配列のサイズ。
 *  @return         最大値。
 *  @details
 *  この関数は配列内の最大値を線形探索で見つけます。
 *
    @code
    int numbers[] = {3, 7, 2, 9, 1};
    int max = findMax(numbers, 5);
    printf("最大値: %d\n", max);  // 出力: 最大値: 9
    @endcode
 */
int findMax(const int *arr, size_t size);

/**
 *  @brief          環境変数の設定例を表示します。
 *  @details        以下の形式で環境変数を設定してください。
    @verbatim
    export PATH=/usr/local/bin:$PATH
    export CC=gcc
    export CFLAGS="-Wall -O2"
    @endverbatim
 */
void showEnvironmentSetup();

/**
 *  @brief          ビルド手順を表示します。
 *  @details
 *  以下のコマンドを順に実行してください。
 *
    @verbatim
    $ cd project_directory
    $ mkdir build
    $ cd build
    $ cmake ..
    $ make
    $ make install
    @endverbatim
 */
void showBuildInstructions();

/**
 *  @brief          エラーコードを返します。
 *  @return         エラーコード。
 *  @details
 *  以下のようにエラーコードを処理します:
 *
 *  ```c
    int result = getErrorCode();
    if (result != 0) {
        fprintf(stderr, "Error: %d\n", result);
        return EXIT_FAILURE;
    }
 *  ```
 */
int getErrorCode();

/**
 *  式のサンプル 1
    @f[
        (1 + 2 + 3) +
        (4 + 5 + 6) +
        (7 + 8 + 9) +
    @f]
 */

/**
 *  式のサンプル 2
    @f$ \sum_{k=1}^n a_k @f$
 */

/**
 *  式のサンプル 3 は @f$ \sum_{k=1}^n a_k @f$ です。
 */

#define THUMB_RGB565_SIZE  28800   /**< RGB565 タイプのサムネイルサイズ @f$ (160 * 90 * 2) @f$。 */

/**
 *  @defgroup       MathFunctions "Mathematical Functions"
 *  @brief          Provides common mathematical functions.
 */

/**
 *  @brief          Calculates the factorial of a number.
 *  @param[in]      n An integer number.
 *  @return         The factorial of @p n.
 */
int factorial(int n);

/**
 *  @ingroup        MathFunctions
 *  @brief          Calculates the greatest common divisor of two numbers.
 *  @param[in]      a First integer.
 *  @param[in]      b Second integer.
 *  @return         The greatest common divisor of @p a and @p b.
 */
int gcd(int a, int b);

/**
 *  @brief          演算を行う関数。
 *  @param[in]      a 演算の入力1。
 *  @param[in]      b 演算の入力2。
 *  @return         演算結果。
 */
int computeOperation(int a, int b);  // @fn を省略

/**
 *  @brief          トークンを表すクラス。
 */
class Token {};  // @class を省略

/**
 *  @brief          生のメモリポインタを操作します。
 *  @param[in,out]  ptr メモリポインタ。
 *  @param[in]      size 操作するサイズ。
 *  @warning        この関数を呼ぶ前に必ず ptr != nullptr を確認してください。
 *  @warning        @p size は実際のメモリサイズを超えてはいけません。
 */
void manipulateRawMemory(void* ptr, size_t size);

/**
 *  @brief          暗号化キーを生成します。
 *  @return         生成されたキー。
 *  @warning        生成されたキーは必ず安全な場所に保存してください。
 *  @warning        デバッグ時でもキーをログに出力しないでください。
 */
char* generateEncryptionKey();

/**
 *  @brief          データベース接続を初期化します。
 *  @param[in]      config 設定情報。
 *  @attention      この関数は main() 関数内で1回だけ呼び出してください。
 *  @attention      cleanup() を呼ぶ前に必ず disconnect() を実行してください。
 */
void initializeDatabase(const Config *config);

/**
 *  @brief          スレッドプールを作成します。
 *  @param[in]      threadCount スレッド数。
 *  @attention      @p threadCount は CPU コア数以下に設定してください。
 *  @attention      他のスレッドプールが動作中の場合は先に停止してください。
 */
void createThreadPool(int threadCount);

/**
 *  @brief          高速ソートアルゴリズムを提供します。
 *  @param[in,out]  data ソートするデータ。
 *  @note           このアルゴリズムはクイックソートを基に最適化されています。
 *  @note           平均時間計算量は O(n log n)、最悪時間計算量は O(n²) です。
 *  @note           安定ソートではありません。
 */
void fastSort(Data *data);

/**
 *  @brief          HTTP リクエストを送信します。
 *  @param[in]      url リクエスト URL。
 *  @return         レスポンス内容。
 *  @note           内部で libcurl ライブラリを使用しています。
 *  @note           タイムアウト値は 30 秒に設定されています。
 *  @note           SSL 証明書の検証を有効にしています。
 */
char *sendHttpRequest(const char *url);

/**
 *  @brief          大量のデータを処理します。
 *  @param[in]      dataset 処理するデータセット。
 *  @remarks        10 万件以上のデータの場合は並列処理版の使用を推奨します。
 *  @remarks        メモリ使用量はデータサイズの約 1.5 倍になります。
 *  @remarks        処理中にプログレスバーを表示することを推奨します。
 */
void processLargeDataset(const Dataset *dataset);

/**
 *  @brief          設定ファイルを読み込みます。
 *  @param[in]      filePath ファイルパス。
 *  @return         設定内容。
 *  @remarks        起動時のパフォーマンスを向上させるため、設定をキャッシュすることを推奨します。
 */
Config *loadConfiguration(const char *filePath);

/**
 *  @brief          金融取引を実行します。
 *  @param[in]      transaction 取引情報。
 *  @param[in]      account 口座情報。
 *  @return         取引結果。
 *
 *  @attention      取引実行前に必ず口座残高を確認してください。
 *  @warning        取引が失敗した場合でも重複実行は禁止です。
 *  @note           取引履歴は自動的にデータベースに保存されます。
 *  @remarks        高頻度取引の場合はバッチ処理の使用を検討してください。
 */
TransactionResult *executeTransaction(const Transaction *transaction, 
                                      const Account *account);

/**
 *  @brief          This function does something important.
 *
 *  @param[in]      param1 Description of param1.
 *  @return         Description of return value.
 */
int exampleFunction(int param1) {
    // Function implementation
    return 0;
}

/**
 *  \brief          This function does something important.
 *
 *  \param[in]      param1 Description of param1.
 *  \return         Description of return value.
 */
int exampleFunction(int param1) {
    // Function implementation
    return 0;
}