# 通知設計書 29-across() ...引数非推奨

## 概要

本ドキュメントは、dplyrパッケージの `across()` 関数において `...` 引数が非推奨となったことに関する通知の設計書です。

### 本通知の処理概要

この通知は、`across()` 関数で `...` を通じて追加引数を指定した場合に発生する非推奨警告の処理内容を定義します。

**業務上の目的・背景**：`across()` の `...` 引数は、`.fns` に渡す関数への追加引数を指定するために使用されていましたが、この引数がいつ評価されるか（1回だけか、グループごとか）が明確でないという問題がありました。この曖昧さを解消するため、dplyr 1.1.0で `...` 引数は非推奨となり、代わりにラムダ関数（無名関数）内で追加引数を直接指定することが推奨されるようになりました。

**通知の送信タイミング**：`across()` 関数を呼び出し、`...` に引数が渡された場合に警告が発生します。これは `across()` 関数の実行時に検出されます。

**通知の受信者**：dplyrパッケージを使用するRユーザー（データサイエンティスト、統計分析者、Rプログラマー）が対象です。特に、`across()` で追加引数を使用している既存コードの保守者に向けた通知です。

**通知内容の概要**：警告メッセージとして「`across(...)`の使用は非推奨であり、ラムダ関数を通じて追加引数を指定すべき」という内容が表示されます。具体的な移行例も提示されます。

**期待されるアクション**：受信者は `across(a:b, mean, na.rm = TRUE)` のような形式を `across(a:b, \(x) mean(x, na.rm = TRUE))` のようなラムダ関数形式に変更することが期待されます。

## 通知種別

コンソール警告（lifecycle::deprecate_warn）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（関数実行時即時） |
| 優先度 | 中 |
| リトライ | 無 |

### 送信先決定ロジック

Rセッション内で `across()` を呼び出し、`...` に引数が渡された場合にコンソールを通じて警告メッセージが表示されます。この警告は `lifecycle` パッケージの `deprecate_warn()` 関数により管理されます。

## 通知テンプレート

### コンソール警告の場合

| 項目 | 内容 |
|-----|------|
| 送信元 | dplyrパッケージ |
| 送信元名称 | lifecycle::deprecate_warn |
| 形式 | テキスト |

### 本文テンプレート

```
The `...` argument of `across()` is deprecated as of dplyr 1.1.0.
Supply arguments directly to `.fns` through an anonymous function instead.

  # Previously
  across(a:b, mean, na.rm = TRUE)

  # Now
  across(a:b, \(x) mean(x, na.rm = TRUE))
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| when | 非推奨となったバージョン | ハードコード値 "1.1.0" | Yes |
| what | 非推奨となった機能 | ハードコード値 "across(...)" | Yes |
| details | 追加情報（移行例） | ハードコード値（複数行） | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 関数呼び出し | `across(..., extra_arg = value)` | `...` に引数が渡された | `!missing(...)` で判定 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| `...` が空の場合 | 追加引数がないため警告不要 |
| ラムダ関数を使用している場合 | 推奨される使用方法 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[across関数呼び出し] --> B[引数解析]
    B --> C[setup処理]
    C --> D{...に引数あり?}
    D -->|Yes| E[lifecycle::deprecate_warn発行]
    D -->|No| F[通常処理継続]
    E --> G[警告メッセージ表示]
    G --> F
    F --> H[関数適用処理]
```

## データベース参照・更新仕様

### 参照テーブル一覧

該当なし（インメモリ処理のみ）

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 該当なし | この通知は警告のみで、エラーは発生しない | - |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（リトライなし） |
| リトライ間隔 | - |
| リトライ対象エラー | - |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| セッションあたり | lifecycleパッケージのデフォルト動作（同一IDは1回のみ） |

### 配信時間帯

制限なし（関数呼び出し時に即時発行）

## セキュリティ考慮事項

特になし。本通知はユーザーコンソールへの警告表示のみで、個人情報やセキュリティに関わるデータは含まれません。

## 備考

- この非推奨警告は dplyr 1.1.0 で導入されました
- `id = "dplyr-across-fns-dots"` により警告が識別されます
- 警告発行後も、`...` の引数は引き続き `.fns` に渡されます
- `if_any()` と `if_all()` 関数にも同様の制限が適用されます

---

## コードリーディングガイド

本通知を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

まず、`across()` の引数構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | across.R | `R/across.R` | `across()` 関数のシグネチャと `...` 引数の位置を理解する |

**読解のコツ**: `...` 引数がどのように `.fns` の関数に渡されるかを理解することが重要です。

#### Step 2: エントリーポイントを理解する

処理の起点となる関数を特定します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | across.R | `R/across.R` | `across()` 関数の定義 |

**主要処理フロー**:
1. **行216**: `across()` 関数の定義（`function(.cols, .fns, ..., .names = NULL, .unpack = FALSE)`）
2. **行255-263**: `across_setup()` 呼び出し
3. **行265-281**: `...` の非推奨チェック

#### Step 3: 非推奨チェックロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | across.R | `R/across.R` | `!missing(...)` による検出と警告発行 |

**主要処理フロー**:
- **行265**: `if (!missing(...))` による `...` の存在チェック
- **行266-273**: 詳細メッセージの定義（移行例）
- **行274-280**: `lifecycle::deprecate_warn()` 呼び出し
- **行279**: ID "dplyr-across-fns-dots"

### プログラム呼び出し階層図

```
across(.cols, .fns, ..., .names, .unpack)
    │
    ├─ peek_mask() - データマスク取得
    │
    ├─ enquo(.cols), enquo(.fns) - 引数のキャプチャ
    │
    ├─ across_setup() - 設定処理
    │
    └─ !missing(...)
           │
           └─ TRUE: lifecycle::deprecate_warn()
                  │
                  └─ 警告メッセージ発行（移行例付き）
```

### データフロー図

```
[入力]               [処理]                    [出力]

... 引数 ───▶ !missing(...) ───▶ TRUE
     │              │                    │
     │              └─▶ deprecate_warn() ─┴─▶ 警告メッセージ
     │
     └──────────────────────────────────────▶ .fnsに渡される
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| across.R | `R/across.R` | ソース | across関数と非推奨チェックの実装 |
| lifecycle | 外部パッケージ | 依存関係 | deprecate_warn関数の提供 |
