String#insert: レビュー指摘を反映して説明を整理

PR #2925 への対応。znz のレビュー指摘を反映:
- 最初の段落は要約のみとし、pos が正/負の場合の説明を後段に分けた
- 正の場合は self[pos, 0] = other と同じ操作である旨を明記
- 削除されていた @see [[m:String#[]=]] を復活
- 例を PR 説明のとおり充実させ、正/負それぞれで insert と []= の
  異同が分かるようにした(出力は Ruby 3.4 で確認済み)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: znz

refm/api/src/_builtin/String

@@ -1815,23 +1815,27 @@ offset が負の場合、文字列の末尾から数えた位置から探索し
 --- insert(pos, other) -> self
 
 文字列 other を self に挿入して self を返します。
-pos が正の場合、other を開始インデックスに挿入します。
 
-#@samplecode 例
-'foo'.insert(1, 'bar') # => "fbaroo"
-#@end
+pos が正の場合、pos 番目の文字の直前に文字列 other を挿入します。
+self[pos, 0] = other と同じ操作です。
 
 pos が負の場合、self の末尾から逆方向に数えて pos+1 (self[index] の後) に other を挿入します。
-pos 番目の文字の直前に文字列 other を挿入します。
-self[pos, 0] = other と同じ操作です。
 
 @param pos      文字列を挿入するインデックス
 @param other    挿入する文字列
 
 #@samplecode 例
-'foo'.insert(-2, 'bar') # => "fobaro"
+# pos が正の場合、String#insert と String#[]= は同じ操作を行う
+'foo'.insert(1, 'bar')               # => "fbaroo"
+str = 'foo'; str[1, 0] = 'bar'; str  # => "fbaroo"
+
+# pos が負の場合、String#insert と String#[]= は異なる操作を行う
+'foo'.insert(-1, 'bar')              # => "foobar"
+str = 'foo'; str[-1, 0] = 'bar'; str # => "fobaro"
 #@end
 
+@see [[m:String#[]=]]
+
 --- intern -> Symbol
 --- to_sym -> Symbol