解 説

replaceWith()はある要素を指定されたHTMLやDOMエレメントで置き換えるものとリファレンスでは説明されていますが、少しわかりにくいので解説します。
ざっくりとみると、html()と働きが似ています。
html()は指定したタグの中身をhtmlタグ付きで変えることができますが、指定したタグ自体は変わりません。
replaceWith()は指定したタグの中身をhtml付きで変えることができます。更に指定したタグ自体も変えてしまいます。

html()のサンプル
replaceWith()のサンプル

これらのサンプルはhtml()を使用した場合とreplaceWith()を使用した場合の違いを見るものです。
結果としてhtml()を使用した場合は、<h1><h2>サンプル</h2></h1>となります。
replaceWith()は、<h2>サンプル</h2>となります。
HTMLコード

<h1>Sample</h1>

htmlを使ったjQueryコード

$(function(){
  $('h1').html('<h2>サンプル</h2>');
});

replaceWithを使ったjQueryコード

$(function(){
  $('h1').replaceWith('<h2>サンプル</h2>');
});

replaceWith()の本質的な使い方

先程の例はreplaceWith()のざっくりとした性質をみたものですが、本来はもっと用途が広いものです。

タグの置き換え

引数にタグを指定するとセレクタで指定したタグに置き換えてくれます。ただし、タグの中身まで変更されます。
これは先の例で見たとおりです。今回のサンプルはタグのみの指定のため、空のh2タグができます。

サンプル

<h1>Sample</h1>

$(function(){
  $('h1').replaceWith('<h2>');
});

jQueryオブジェクトの指定で移動

replaceWith()の引数にjQueryオブジェクトを指定すると指定した要素のノードすべてが移動します。
ポイントはコピーではなく移動する点です。

サンプル

$('h1').replaceWith($('h2'));

タグのみの入れ替え

何らかの理由で内容はそのままで、動的にタグを付け替えたい場合には簡単に実行できるメソッドは用意されていません。
replaceWith()を使うと次のような記述で実現できます。

サンプル

$('h1').replaceWith('<h2>' + $('h1').text() + '</h2>');

引数にfunctionの指定

replaceWith()の引数にfunctionを指定してその戻り値を使うことができます。
liの内容が順番に取れているところが興味深いです。

サンプル

jQueryコード

$(function(){
  $('p').replaceWith(function(){
	return '<p>' + $('li').text() + '</p>';			
  });
});

HTMLコード

<h1>Sample</h1>
  <p>Lorem ipsum dolor sit amet.</p>
  <ul>
    <li>no1</li>
    <li>no2</li>
    <li>no3</li>
  </ul>