RDocのコードフォーマット記法を修正

ActionView::Helpers::TextHelperのドキュメントで、+String#sub+という記述が正しくレンダリングされない問題を修正しました。RDocの記法ルールに従い、<tt>String#sub</tt>に変更することで、APIドキュメントの表示が正常化されます。

背景

RDocでは、インラインコードのマークアップに+code+と<tt>code</tt>の2つの記法が使用できます。しかし、+記法は単純な識別子にのみ有効で、String#subのようにシャープ記号を含むメソッド参照では機能しません。この制約により、Rails Edge APIドキュメントのTextHelper#highlightのページで、:highlighterオプションの説明文が意図した形式で表示されていませんでした。

RDocパーサーは+String#sub+を正しく解釈できず、コードとして認識されないままプレーンテキストとして出力されていました。

技術的な変更

actionview/lib/action_view/helpers/text_helper.rbのhighlightメソッドのドキュメントコメントを修正しました。

変更前:

# [+:highlighter+]
#   The highlighter string. Uses <tt>\1</tt> as the placeholder for a
#   phrase, similar to +String#sub+. Defaults to <tt>"<mark>\1</mark>"</tt>.
#   This option is ignored if a block is specified.

変更後:

# [+:highlighter+]
#   The highlighter string. Uses <tt>\1</tt> as the placeholder for a
#   phrase, similar to <tt>String#sub</tt>. Defaults to <tt>"<mark>\1</mark>"</tt>.
#   This option is ignored if a block is specified.

+String#sub+を<tt>String#sub</tt>に置き換えることで、RDocパーサーが確実にコードとして認識し、適切なフォーマットで出力されるようになります。同じ文中の<tt>\1</tt>や<tt>"<mark>\1</mark>"</tt>と記法を統一することで、ドキュメントの一貫性も向上しています。

設計判断

<tt>タグによる明示的なマークアップが選択されました。

RDocの+記法はシンプルですが、適用範囲に制約があります。一方、<tt>タグはHTMLタグベースの記法であり、より複雑な構文を確実にマークアップできます。PRの説明にある通り、「The simple + style doesn't work with more complicated snippets」という実用上の判断から、確実性を重視した記法への統一が行われています。

同一の説明文内で複数のコード断片が存在する場合、すべて同じマークアップ記法で統一することで、ドキュメント生成の予測可能性が高まります。

まとめ

本PRは、RDocのマークアップ記法の制約に対処するための1文字の修正です。+から<tt>への変更により、メソッド参照を含む複雑なコード断片が正しくレンダリングされるようになり、Rails APIドキュメントの品質が向上します。