#80118 go/ast: standardize deprecated comment tags

AIによる要約であり、誤りを含む場合があります。

概要

go/doc パッケージに非推奨（Deprecated）コメントタグの仕様を一元化し、構造体フィールドやインターフェースメソッドへのインラインコメント対応など、ツール間で異なる実装の標準化を図るproposal。

ステータス変更

(新規) → active
2026年6月24日の週次Proposal Reviewミーティング（@adonovan, @bradfitz, @cherrymui, @griesemer, @ianlancetaylor, @neild, @rolandshoemaker参加）にてactiveリストへ追加された。議論開始として「added to minutes」の状態であり、まだ承認・却下の判断はなされていない。

技術的背景

現状の問題点

Go言語では Deprecated: で始まるdocコメントのパラグラフを非推奨マーカーとして使用する慣習が存在するが、その定義はGitHub Wikiページ（go.dev/wiki/Deprecated）に散在しており、以下の問題がある。

仕様の曖昧さ: どこまでが非推奨メッセージか（最初のパラグラフのみか、後続パラグラフも含むか）が不明確（#38743で指摘）
ツール間の不一致: gopls、staticcheck、pkg.go.dev それぞれが独自の Deprecated: 検出ロジックを持ち、挙動がバラバラ
構造体フィールド・インターフェースメソッドへの非対応: これらはパラグラフ形式のdocコメントを持てないため、非推奨マーカーを付ける方法が不明瞭。開発者がためらう原因となっている
定義の場所: Wikiという非公式な場所にあり、参照しづらい

// 現状の問題：構造体フィールドへの非推奨マーカーの書き方が標準化されていない
type S struct {
    Old int // フィールドにどう書けば非推奨と認識されるか不明確
    New int
}

提案された解決策

3つの変更を提案している。

定義の移動: 非推奨タグの定義をWikiから go.dev/cmd/go などの公式ドキュメントへ移動し、短縮URL（例: go.dev/s/deprecated）を整備する
インラインコメント対応の追加: 構造体フィールドやインターフェースメソッドの行末コメント（// ... Deprecated: ...）においても非推奨マーカーを受け付けるよう仕様を拡張する。行コメントにはパラグラフがないため、行中のどこかに Deprecated: が含まれていれば認識する
go/doc パッケージへの中央関数の追加: func Deprecation(*CommentGroup) string のような関数を go/doc パッケージに追加し、goplsの astutil.Deprecation など各ツールが独自実装を持つ現状を統合する

これによって何ができるようになるか

構造体フィールドやインターフェースメソッドの非推奨化が標準的に書けるようになる。また、ツール間で検出ロジックが統一され、gopls・staticcheck・pkg.go.devが一貫した動作をする。

コード例

// Before: 構造体フィールドへの非推奨化の標準的な書き方がなく、ツールによって認識されないケースがあった
type ResponseRecorder struct {
    HeaderMap http.Header // 使えるが、非推奨として認識されないことがある
}
// After: インライン Deprecated: がフィールド・メソッドで標準的に認識される
type S struct {
    Old int // the old field. Deprecated: it's old; use S.New instead.
    New int  // the new field
}
type I interface {
    Old() // the old method. Deprecated: it's old; use I.New instead.
    New() // the new method
}
// Before: 各ツールが独自に非推奨を検出
// gopls: astutil.Deprecation() を独自実装
// staticcheck: 独自の検出ロジック (SA1019)
// After: 全ツールが go/doc パッケージの共通関数を利用
import "go/doc"
msg := doc.Deprecation(commentGroup) // 標準化された検出

議論のハイライト

パッケージの選択: 当初 go/ast への追加が提案されていたが、@ianlancetaylor により go/doc または go/doc/comment のほうが適切と指摘され、提案タイトルも変更された（go/ast は go/doc/comment では使われていない）
コーパス分析の必要性: @mvdan が既存の人気Goモジュール群への影響調査（新しいヒューリスティックが実際の Deprecated: コメントをカバーできるか、誤検出がないか）を実施すべきと提案。提案者の @aputman が対応を約束した
既存のドキュメント: @ChrisHines により、#55083 の成果として go.dev/doc/comment#deprecations に既に非推奨に関するセクションが追加済みであると指摘された。提案はこれをさらに発展させるもの
ツールの乱立: gopls（deprecated アナライザー）、staticcheck（SA1019チェック）、pkg.go.dev がそれぞれ独立した実装を持っており、統合の必要性が浮き彫りになっている
背景Issue: #38743（非推奨コメントの文法仕様化）や #10909（非推奨慣習の文書化）など、6年以上にわたる関連議論の集大成としての位置づけ

Go Proposal Weekly Digest

go/ast: standardize deprecated comment tags

要約

概要