From 463eb47011c036b19c79bffc33d893f58894dd05 Mon Sep 17 00:00:00 2001
From: Arvid Norberg <arvid@libtorrent.org>
Date: Sat, 24 Nov 2007 20:48:51 +0000
Subject: [PATCH] updated documentation

---
 docs/manual.html | 392 ++++++++++++++++++++++++++++-------------------
 docs/manual.rst  |  30 ++--
 2 files changed, 258 insertions(+), 164 deletions(-)

diff --git a/docs/manual.html b/docs/manual.html
index d592caff8..f861a8787 100644
--- a/docs/manual.html
+++ b/docs/manual.html
@@ -25,172 +25,176 @@
 <p class="topic-title first"><a name="table-of-contents">Table of contents</a></p>
 <ul class="simple">
 <li><a class="reference" href="#overview" id="id18" name="id18">overview</a></li>
-<li><a class="reference" href="#primitive-network-types" id="id19" name="id19">primitive network types</a></li>
+<li><a class="reference" href="#network-primitives" id="id19" name="id19">network primitives</a></li>
 <li><a class="reference" href="#session" id="id20" name="id20">session</a><ul>
 <li><a class="reference" href="#id1" id="id21" name="id21">session()</a></li>
 <li><a class="reference" href="#id2" id="id22" name="id22">~session()</a></li>
 <li><a class="reference" href="#abort" id="id23" name="id23">abort()</a></li>
 <li><a class="reference" href="#add-torrent" id="id24" name="id24">add_torrent()</a></li>
-<li><a class="reference" href="#remove-torrent-find-torrent-get-torrents" id="id25" name="id25">remove_torrent() find_torrent() get_torrents()</a></li>
-<li><a class="reference" href="#set-upload-rate-limit-set-download-rate-limit-upload-rate-limit-download-rate-limit" id="id26" name="id26">set_upload_rate_limit() set_download_rate_limit() upload_rate_limit() download_rate_limit()</a></li>
-<li><a class="reference" href="#set-max-uploads-set-max-connections" id="id27" name="id27">set_max_uploads() set_max_connections()</a></li>
-<li><a class="reference" href="#num-uploads-num-connections" id="id28" name="id28">num_uploads() num_connections()</a></li>
-<li><a class="reference" href="#set-max-half-open-connections-max-half-open-connections" id="id29" name="id29">set_max_half_open_connections() max_half_open_connections()</a></li>
-<li><a class="reference" href="#set-ip-filter" id="id30" name="id30">set_ip_filter()</a></li>
-<li><a class="reference" href="#status" id="id31" name="id31">status()</a></li>
-<li><a class="reference" href="#is-listening-listen-port-listen-on" id="id32" name="id32">is_listening() listen_port() listen_on()</a></li>
-<li><a class="reference" href="#pop-alert-set-severity-level" id="id33" name="id33">pop_alert() set_severity_level()</a></li>
-<li><a class="reference" href="#add-extension" id="id34" name="id34">add_extension()</a></li>
-<li><a class="reference" href="#set-settings-set-pe-settings" id="id35" name="id35">set_settings() set_pe_settings()</a></li>
-<li><a class="reference" href="#set-peer-proxy-set-web-seed-proxy-set-tracker-proxy-set-dht-proxy" id="id36" name="id36">set_peer_proxy() set_web_seed_proxy() set_tracker_proxy() set_dht_proxy()</a></li>
-<li><a class="reference" href="#peer-proxy-web-seed-proxy-tracker-proxy-dht-proxy" id="id37" name="id37">peer_proxy() web_seed_proxy() tracker_proxy() dht_proxy()</a></li>
-<li><a class="reference" href="#start-dht-stop-dht-set-dht-settings-dht-state" id="id38" name="id38">start_dht() stop_dht() set_dht_settings() dht_state()</a></li>
-<li><a class="reference" href="#add-dht-node-add-dht-router" id="id39" name="id39">add_dht_node() add_dht_router()</a></li>
+<li><a class="reference" href="#remove-torrent" id="id25" name="id25">remove_torrent()</a></li>
+<li><a class="reference" href="#find-torrent-get-tHTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Connection: close
Transfer-Encoding: chunked
Cache-Control: max-age=0, private, must-revalidate, no-transform
Set-Cookie: i_like_gitea=0709e7d0556339d7; Path=/; HttpOnly; Secure; SameSite=Lax
Set-Cookie: _csrf=ap7zcmluPF8gqfhzZlRzAShfTIc6MTc1MzI2ODEwNTA0Mjk1MjMyNA; Path=/; Max-Age=86400; HttpOnly; Secure; SameSite=Lax
X-Frame-Options: SAMEORIGIN
Date: Wed, 23 Jul 2025 10:55:05 GMT
X-Cache-Status: HIT
X-Cache-Age: 0

7000
From 463eb47011c036b19c79bffc33d893f58894dd05 Mon Sep 17 00:00:00 2001
From: Arvid Norberg <arvid@libtorrent.org>
Date: Sat, 24 Nov 2007 20:48:51 +0000
Subject: [PATCH] updated documentation

---
 docs/manual.html | 392 ++++++++++++++++++++++++++++-------------------
 docs/manual.rst  |  30 ++--
 2 files changed, 258 insertions(+), 164 deletions(-)

diff --git a/docs/manual.html b/docs/manual.html
index d592caff8..f861a8787 100644
--- a/docs/manual.html
+++ b/docs/manual.html
@@ -25,172 +25,176 @@
 <p class="topic-title first"><a name="table-of-contents">Table of contents</a></p>
 <ul class="simple">
 <li><a class="reference" href="#overview" id="id18" name="id18">overview</a></li>
-<li><a class="reference" href="#primitive-network-types" id="id19" name="id19">primitive network types</a></li>
+<li><a class="reference" href="#network-primitives" id="id19" name="id19">network primitives</a></li>
 <li><a class="reference" href="#session" id="id20" name="id20">session</a><ul>
 <li><a class="reference" href="#id1" id="id21" name="id21">session()</a></li>
 <li><a class="reference" href="#id2" id="id22" name="id22">~session()</a></li>
 <li><a class="reference" href="#abort" id="id23" name="id23">abort()</a></li>
 <li><a class="reference" href="#add-torrent" id="id24" name="id24">add_torrent()</a></li>
-<li><a class="reference" href="#remove-torrent-find-torrent-get-torrents" id="id25" name="id25">remove_torrent() find_torrent() get_torrents()</a></li>
-<li><a class="reference" href="#set-upload-rate-limit-set-download-rate-limit-upload-rate-limit-download-rate-limit" id="id26" name="id26">set_upload_rate_limit() set_download_rate_limit() upload_rate_limit() download_rate_limit()</a></li>
-<li><a class="reference" href="#set-max-uploads-set-max-connections" id="id27" name="id27">set_max_uploads() set_max_connections()</a></li>
-<li><a class="reference" href="#num-uploads-num-connections" id="id28" name="id28">num_uploads() num_connections()</a></li>
-<li><a class="reference" href="#set-max-half-open-connections-max-half-open-connections" id="id29" name="id29">set_max_half_open_connections() max_half_open_connections()</a></li>
-<li><a class="reference" href="#set-ip-filter" id="id30" name="id30">set_ip_filter()</a></li>
-<li><a class="reference" href="#status" id="id31" name="id31">status()</a></li>
-<li><a class="reference" href="#is-listening-listen-port-listen-on" id="id32" name="id32">is_listening() listen_port() listen_on()</a></li>
-<li><a class="reference" href="#pop-alert-set-severity-level" id="id33" name="id33">pop_alert() set_severity_level()</a></li>
-<li><a class="reference" href="#add-extension" id="id34" name="id34">add_extension()</a></li>
-<li><a class="reference" href="#set-settings-set-pe-settings" id="id35" name="id35">set_settings() set_pe_settings()</a></li>
-<li><a class="reference" href="#set-peer-proxy-set-web-seed-proxy-set-tracker-proxy-set-dht-proxy" id="id36" name="id36">set_peer_proxy() set_web_seed_proxy() set_tracker_proxy() set_dht_proxy()</a></li>
-<li><a class="reference" href="#peer-proxy-web-seed-proxy-tracker-proxy-dht-proxy" id="id37" name="id37">peer_proxy() web_seed_proxy() tracker_proxy() dht_proxy()</a></li>
-<li><a class="reference" href="#start-dht-stop-dht-set-dht-settings-dht-state" id="id38" name="id38">start_dht() stop_dht() set_dht_settings() dht_state()</a></li>
-<li><a class="reference" href="#add-dht-node-add-dht-router" id="id39" name="id39">add_dht_node() add_dht_router()</a></li>
+<li><a class="reference" href="#remove-torrent" id="id25" name="id25">remove_torrent()</a></li>
+<li><a class="reference" href="#find-torrent-get-t
3000
id150">file format</a></li>
+<li><a class="reference" href="#fast-resume" id="id153" name="id153">fast resume</a><ul>
+<li><a class="reference" href="#file-format" id="id154" name="id154">file format</a></li>
 </ul>
 </li>
-<li><a class="reference" href="#threads" id="id151" name="id151">threads</a></li>
-<li><a class="reference" href="#storage-allocation" id="id152" name="id152">storage allocation</a><ul>
-<li><a class="reference" href="#sparse-allocation" id="id153" name="id153">sparse allocation</a></li>
-<li><a class="reference" href="#full-allocation" id="id154" name="id154">full allocation</a></li>
-<li><a class="reference" href="#compact-allocation" id="id155" name="id155">compact allocation</a></li>
+<li><a class="reference" href="#threads" id="id155" name="id155">threads</a></li>
+<li><a class="reference" href="#storage-allocation" id="id156" name="id156">storage allocation</a><ul>
+<li><a class="reference" href="#sparse-allocation" id="id157" name="id157">sparse allocation</a></li>
+<li><a class="reference" href="#full-allocation" id="id158" name="id158">full allocation</a></li>
+<li><a class="reference" href="#compact-allocation" id="id159" name="id159">compact allocation</a></li>
 </ul>
 </li>
-<li><a class="reference" href="#extensions" id="id156" name="id156">extensions</a><ul>
-<li><a class="reference" href="#metadata-from-peers" id="id157" name="id157">metadata from peers</a></li>
-<li><a class="reference" href="#http-seeding" id="id158" name="id158">HTTP seeding</a></li>
+<li><a class="reference" href="#extensions" id="id160" name="id160">extensions</a><ul>
+<li><a class="reference" href="#metadata-from-peers" id="id161" name="id161">metadata from peers</a></li>
+<li><a class="reference" href="#http-seeding" id="id162" name="id162">HTTP seeding</a></li>
 </ul>
 </li>
-<li><a class="reference" href="#filename-checks" id="id159" name="id159">filename checks</a></li>
-<li><a class="reference" href="#acknowledgments" id="id160" name="id160">acknowledgments</a></li>
+<li><a class="reference" href="#filename-checks" id="id163" name="id163">filename checks</a></li>
+<li><a class="reference" href="#acknowledgments" id="id164" name="id164">acknowledgments</a></li>
 </ul>
 </div>
 <div class="section">
@@ -201,7 +205,7 @@ the <tt class="docutils literal"><span class="pre">session</span></tt>, it conta
 <ul>
 <li><p class="first">construct a session</p>
 </li>
-<li><p class="first">parse .torrent-files and add them to the session (see <a class="reference" href="#bdecode-bencode">bdecode() bencode()</a>)</p>
+<li><p class="first">parse .torrent-files and add them to the session (see <a class="reference" href="#bdecode-bencode">bdecode() bencode()</a> and <a class="reference" href="#add-torrent">add_torrent()</a>)</p>
 </li>
 <li><p class="first">main loop (see <a class="reference" href="#session">session</a>)</p>
 <blockquote>
@@ -213,7 +217,7 @@ the <tt class="docutils literal"><span class="pre">session</span></tt>, it conta
 </blockquote>
 </li>
 <li><p class="first">save resume data for all torrent_handles (optional, see
-<a href="#id161" name="id162"><span class="problematic" id="id162">`write_resume_data()`_</span></a>)</p>
+<a class="reference" href="#write-resume-data">write_resume_data()</a>)</p>
 </li>
 <li><p class="first">destruct session object</p>
 </li>
@@ -221,7 +225,7 @@ the <tt class="docutils literal"><span class="pre">session</span></tt>, it conta
 <p>Each class and function is described in this manual.</p>
 </div>
 <div class="section">
-<h1><a id="primitive-network-types" name="primitive-network-types">primitive network types</a></h1>
+<h1><a id="network-primitives" name="network-primitives">network primitives</a></h1>
 <p>There are a few typedefs in the <tt class="docutils literal"><span class="pre">libtorrent</span></tt> namespace which pulls
 in network types from the <tt class="docutils literal"><span class="pre">asio</span></tt> namespace. These are:</p>
 <pre class="literal-block">
@@ -239,6 +243,7 @@ udp::endpoint
 </pre>
 <p>Which are the endpoint types used in libtorrent. An endpoint is an address
 with an associated port.</p>
+<p>For documentation on these types, please refer to the <a class="reference" href="http://asio.sourceforge.net/asio-0.3.8/doc/asio/reference.html">asio documentation</a>.</p>
 </div>
 <div class="section">
 <h1><a id="session" name="session">session</a></h1>
@@ -274,7 +279,13 @@ class session: public boost::noncopyable
 
         session_proxy abort();
 
-        void remove_torrent(torrent_handle const&amp; h);
+        enum options_t
+        {
+                none = 0,
+                delete_files = 1
+        };
+
+        void remove_torrent(torrent_handle const&amp; h, int options = none);
         torrent_handle find_torrent(sha_hash const&amp; ih);
         std::vector&lt;torrent_handle&gt; get_torrents() const;
 
@@ -456,16 +467,27 @@ have metadata. See <tt class="docutils literal"><span class="pre">torrent_handle
 <tt class="docutils literal"><span class="pre">tracker_url</span></tt> can be 0.</p>
 </div>
 <div class="section">
-<h2><a id="remove-torrent-find-torrent-get-torrents" name="remove-torrent-find-torrent-get-torrents">remove_torrent() find_torrent() get_torrents()</a></h2>
+<h2><a id="remove-torrent" name="remove-torrent">remove_torrent()</a></h2>
+<blockquote>
+<pre class="literal-block">
+void remove_torrent(torrent_handle const&amp; h, int options = none);
+</pre>
+</blockquote>
+<p><tt class="docutils literal"><span class="pre">remove_torrent()</span></tt> will close all peer connections associated with the torrent and tell
+the tracker that we've stopped participating in the swarm. The optional second argument
+<tt class="docutils literal"><span class="pre">options</span></tt> can be used to delete all the files downloaded by this torrent. To do this, pass
+in the value <tt class="docutils literal"><span class="pre">session::delete_files</span></tt>. The removal of the torrent is asyncronous, there is
+no guarantee that adding the same torrent immediately after it was removed will not throw
+a <a class="reference" href="#duplicate-torrent">duplicate_torrent</a> exception.</p>
+</div>
+<div class="section">
+<h2><a id="find-torrent-get-torrents" name="find-torrent-get-torrents">find_torrent() get_torrents()</a></h2>
 <blockquote>
 <pre class="literal-block">
-void remove_torrent(torrent_handle const&amp; h);
 torrent_handle find_torrent(sha_hash const&amp; ih);
 std::vector&lt;torrent_handle&gt; get_torrents() const;
 </pre>
 </blockquote>
-<p><tt class="docutils literal"><span class="pre">remove_torrent()</span></tt> will close all peer connections associated with the torrent and tell
-the tracker that we've stopped participating in the swarm.</p>
 <p><tt class="docutils literal"><span class="pre">find_torrent()</span></tt> looks for a torrent with the given info-hash. In case there
 is such a torrent in the session, a torrent_handle to that torrent is returned.
 In case the torrent cannot be found, an invalid torrent_handle is returned.</p>
@@ -1401,6 +1423,8 @@ struct torrent_handle
 
         entry write_resume_data() const;
         void force_reannounce() const;
+        void force_reannounce(boost::posix_time::time_duration) const;
+        void scrape_tracker() const;
         void connect_peer(asio::ip::tcp::endpoint const&amp; adr, int source = 0) const;
 
         void set_tracker_login(std::string const&amp; username
@@ -1559,11 +1583,26 @@ thread, this operation is also asynchronous. Once the operation completes, the
 <blockquote>
 <pre class="literal-block">
 void force_reannounce() const;
+void force_reannounce(boost::posix_time::time_duration) const;
 </pre>
 </blockquote>
 <p><tt class="docutils literal"><span class="pre">force_reannounce()</span></tt> will force this torrent to do another tracker request, to receive new
-peers. If the torrent is invalid, queued or in checking mode, this functions will throw
-<a class="reference" href="#invalid-handle">invalid_handle</a>.</p>
+peers. The second overload of <tt class="docutils literal"><span class="pre">force_reannounce</span></tt> that takes a <tt class="docutils literal"><span class="pre">time_duration</span></tt> as
+argument will schedule a reannounce in that amount of time from now.</p>
+</div>
+<div class="section">
+<h2><a id="scrape-tracker" name="scrape-tracker">scrape_tracker()</a></h2>
+<blockquote>
+<pre class="literal-block">
+void scrape_tracker() const;
+</pre>
+</blockquote>
+<p><tt class="docutils literal"><span class="pre">scrape_tracker()</span></tt> will send a scrape request to the tracker. A scrape request queries the
+tracker for statistics such as total number of incomplete peers, complete peers, number of
+downloads etc.</p>
+<p>This request will specifically update the <tt class="docutils literal"><span class="pre">num_complete</span></tt> and <tt class="docutils literal"><span class="pre">num_incomplete</span></tt> fields in
+the <a class="reference" href="#torrent-status">torrent_status</a> struct once it completes. When it completes, it will generate a
+<a class="reference" href="#scrape-reply-alert">scrape_reply_alert</a>. If it fails, it will generate a <a class="reference" href="#scrape-failed-alert">scrape_failed_alert</a>.</p>
 </div>
 <div class="section">
 <h2><a id="connect-peer" name="connect-peer">connect_peer()</a></h2>
@@ -1936,6 +1975,7 @@ struct torrent_status
                 queued_for_checking,
                 checking_files,
                 connecting_to_tracker,
+                downloading_metadata,
                 downloading,
                 finished,
                 seeding,
@@ -2012,6 +2052,10 @@ currently checking existing files.</td>
 <td>The torrent has sent a request to the tracker and is
 currently waiting for a response</td>
 </tr>
+<tr><td><tt class="docutils literal"><span class="pre">downloading_metadata</span></tt></td>
+<td>The torrent is trying to download metadata from peers.
+This assumes the metadata_transfer extension is in use.</td>
+</tr>
 <tr><td><tt class="docutils literal"><span class="pre">downloading</span></tt></td>
 <td>The torrent is being downloaded. This is the state
 most torrents will be in most of the time. The progress
@@ -2362,6 +2406,7 @@ struct session_settings
         bool lazy_bitfields;
         int inactivity_timeout;
         bool use_dht_as_fallback;
+        bool free_torrent_hashes;
 };
 </pre>
 <p><tt class="docutils literal"><span class="pre">user_agent</span></tt> this is the client identification to the tracker.
@@ -2462,6 +2507,13 @@ Default is 10 minutes</p>
 (which it is by default), the DHT will only be used for torrents where
 all trackers in its tracker list has failed. Either by an explicit error
 message or a time out.</p>
+<p><tt class="docutils literal"><span class="pre">free_torrent_hashes</span></tt> determines whether or not the torrent's piece hashes
+are kept in memory after the torrent becomes a seed or not. If it is set to
+<tt class="docutils literal"><span class="pre">true</span></tt> the hashes are freed once the torrent is a seed (they're not
+needed anymore since the torrent won't download anything more). If it's set
+to false they are not freed. If they are freed, the <a class="reference" href="#torrent-info">torrent_info</a> returned
+by get_torrent_info() will return an object that may be incomplete, that
+cannot be passed back to <a class="reference" href="#add-torrent">add_torrent()</a> for instance.</p>
 </div>
 <div class="section">
 <h1><a id="pe-settings" name="pe-settings">pe_settings</a></h1>
@@ -3083,6 +3135,41 @@ struct tracker_warning_alert: torrent_alert
 </pre>
 </div>
 <div class="section">
+<h2><a id="scrape-reply-alert" name="scrape-reply-alert">scrape_reply_alert</a></h2>
+<pre class="literal-block">
+struct scrape_reply_alert: torrent_alert
+{
+        scrape_reply_alert(torrent_handle const&amp; h
+                , int incomplete_
+                , int complete_
+                , std::string const&amp; msg);
+
+        int incomplete;
+        int complete;
+
+        virtual std::auto_ptr&lt;alert&gt; clone() const;
+};
+</pre>
+<p>This alert is generated when a scrape request succeeds. <tt class="docutils literal"><span class="pre">incomplete</span><
15a2
/tt>
+and <tt class="docutils literal"><span class="pre">complete</span></tt> is the data returned in the scrape response. These numbers
+may be -1 if the reponse was malformed.</p>
+</div>
+<div class="section">
+<h2><a id="scrape-failed-alert" name="scrape-failed-alert">scrape_failed_alert</a></h2>
+<pre class="literal-block">
+struct scrape_failed_alert: torrent_alert
+{
+        scrape_failed_alert(torrent_handle const&amp; h
+                , std::string const&amp; msg);
+
+        virtual std::auto_ptr&lt;alert&gt; clone() const;
+};
+</pre>
+<p>If a scrape request fails, this alert is generated. This might be due
+to the tracker timing out, refusing connection or returning an http response
+code indicating an error.</p>
+</div>
+<div class="section">
 <h2><a id="url-seed-alert" name="url-seed-alert">url_seed_alert</a></h2>
 <p>This alert is generated when a HTTP seed name lookup fails. This alert is
 generated as severity level <tt class="docutils literal"><span class="pre">warning</span></tt>.</p>
@@ -3363,7 +3450,8 @@ struct invalid_handle: std::exception
 <div class="section">
 <h2><a id="duplicate-torrent" name="duplicate-torrent">duplicate_torrent</a></h2>
 <p>This is thrown by <a class="reference" href="#add-torrent">add_torrent()</a> if the torrent already has been added to
-the session.</p>
+the session. Since <a class="reference" href="#remove-torrent">remove_torrent()</a> is asynchronous, this exception may
+be thrown if the torrent is removed and then immediately added again.</p>
 <pre class="literal-block">
 struct duplicate_torrent: std::exception
 {
@@ -3484,7 +3572,7 @@ not, set <tt class="docutils literal"><span class="pre">error</span></tt> to a d
 <p>The default storage may compare file sizes and time stamps of the files.</p>
 </div>
 <div class="section">
-<h2><a id="id12" name="id12">write_resume_data()</a></h2>
+<h2><a id="id12" name="id12">write_resume_data( )</a></h2>
 <blockquote>
 <pre class="literal-block">
 void write_resume_data(entry&amp; rd) const = 0;
@@ -3986,12 +4074,6 @@ scripts.</p>
 <p>Project is hosted by sourceforge.</p>
 <p><a class="reference" href="http://sourceforge.net"><img alt="sf_logo" src="http://sourceforge.net/sflogo.php?group_id=7994" /></a></p>
 </div>
-<div class="system-messages section">
-<h1>Docutils System Messages</h1>
-<div class="system-message" id="id161">
-<p class="system-message-title">System Message: <a name="id161">ERROR/3</a> (<tt class="docutils">manual.rst</tt>, line 28); <em><a href="#id162">backlink</a></em></p>
-Duplicate target name, cannot be used as a unique reference: &quot;write_resume_data()&quot;.</div>
-</div>
 </div>
 </body>
 </html>
diff --git a/docs/manual.rst b/docs/manual.rst
index 6d4359b5d..32b0f98a6 100644
--- a/docs/manual.rst
+++ b/docs/manual.rst
@@ -18,7 +18,7 @@ the ``session``, it contains the main loop that serves all torrents.
 The basic usage is as follows:
 
 * construct a session
-* parse .torrent-files and add them to the session (see `bdecode() bencode()`_)
+* parse .torrent-files and add them to the session (see `bdecode() bencode()`_ and `add_torrent()`_)
 * main loop (see session_)
 
 	* query the torrent_handles for progress (see torrent_handle_)
@@ -31,8 +31,8 @@ The basic usage is as follows:
 
 Each class and function is described in this manual.
 
-primitive network types
-=======================
+network primitives
+==================
 
 There are a few typedefs in the ``libtorrent`` namespace which pulls
 in network types from the ``asio`` namespace. These are::
@@ -53,6 +53,11 @@ The ``using`` statements will give easy access to::
 Which are the endpoint types used in libtorrent. An endpoint is an address
 with an associated port.
 
+For documentation on these types, please refer to the `asio documentation`_.
+
+.. _`asio documentation`: http://asio.sourceforge.net/asio-0.3.8/doc/asio/reference.html
+
+
 session
 =======
 
@@ -290,21 +295,27 @@ If the torrent doesn't have a tracker, but relies on the DHT to find peers, the
 ``tracker_url`` can be 0.
 
 
-remove_torrent() find_torrent() get_torrents()
-----------------------------------------------
+remove_torrent()
+----------------
 
 	::
 
 		void remove_torrent(torrent_handle const& h, int options = none);
-		torrent_handle find_torrent(sha_hash const& ih);
-		std::vector<torrent_handle> get_torrents() const;
 
 ``remove_torrent()`` will close all peer connections associated with the torrent and tell
 the tracker that we've stopped participating in the swarm. The optional second argument
 ``options`` can be used to delete all the files downloaded by this torrent. To do this, pass
 in the value ``session::delete_files``. The removal of the torrent is asyncronous, there is
 no guarantee that adding the same torrent immediately after it was removed will not throw
-a ``duplicate_torrent`` exception.
+a duplicate_torrent_ exception.
+
+find_torrent() get_torrents()
+-----------------------------
+
+	::
+
+		torrent_handle find_torrent(sha_hash const& ih);
+		std::vector<torrent_handle> get_torrents() const;
 
 ``find_torrent()`` looks for a torrent with the given info-hash. In case there
 is such a torrent in the session, a torrent_handle to that torrent is returned.
@@ -3563,7 +3574,8 @@ duplicate_torrent
 -----------------
 
 This is thrown by `add_torrent()`_ if the torrent already has been added to
-the session.
+the session. Since `remove_torrent()`_ is asynchronous, this exception may
+be thrown if the torrent is removed and then immediately added again.
 
 ::
 

0