improve documentation

docs/manual.rst

@@ -191,12 +191,7 @@ The format of the magnet URI is:
 **magnet:?xt=urn:btih:** *Base16 encoded info-hash* [ **&dn=** *name of download* ] [ **&tr=** *tracker URL* ]*
 
 In order to download *just* the metadata (.torrent file) from a magnet link, set
-file priorities to 0 in add_torrent_params::file_priorities. It's OK to set the
-priority for more files than what is in the torrent. It may not be trivial to
-know how many files a torrent has before the metadata has been downloaded.
-Additional file priorities will be ignored. By setting a large number of files
-to priority 0, chances are that they will all be set to 0 once the metadata is
-received (and we know how many files there are).
+the torrent_flags::upload_mode flag in add_torrent_params before adding the it.
 
 In this case, when the metadata is received from the swarm, the torrent will
 still be running, but it will disconnect the majority of peers (since connections
@@ -212,8 +207,8 @@ state the torrent is in (checking, downloading or seeding).
 
 To opt-out of the queuing logic, make sure your torrents are added with the
 torrent_flags::auto_managed bit *cleared* from ``add_torrent_params::flags``.
-Or call ``torrent_handle::unset_flags(torrent_flags::auto_managed)`` on the
-torrent handle.
+Or call torrent_handle::unset_flags() and pass in torrent_flags::auto_managed on
+the torrent handle.
 
 The overall purpose of the queuing logic is to improve performance under arbitrary
 torrent downloading and seeding load. For example, if you want to download 100
@@ -294,8 +289,7 @@ once it is ready to start downloading.
 This is conceptually the same as waiting for the ``torrent_checked_alert`` and
 then call::
 
-	h.auto_managed(false);
-	h.pause();
+	h.set_flags(torrent_flags::paused, torrent_flags::paused | torrent_flags::auto_managed);
 
 With the important distinction that it entirely avoids the brief window where
 the torrent is in downloading state.

include/libtorrent/session_handle.hpp

@@ -234,7 +234,12 @@ namespace libtorrent {
 		// ``std::exception`` unless duplicate_is_error is set to false. In that
 		// case, add_torrent() will return the handle to the existing torrent.
 		//
-		// all torrent_handles must be destructed before the session is destructed!
+		// The add_torrent_params class has a flags field. It can be used to
+		// control what state the new torrent will be added in. Common flags to
+		// want to control are torrent_flags::paused and
+		// torrent_flags::auto_managed. In order to add a magnet link that will
+		// just download the metadata, but no payload, set the
+		// torrent_flags::upload_mode flag.
 #ifndef BOOST_NO_EXCEPTIONS
 		torrent_handle add_torrent(add_torrent_params&& params);
 		torrent_handle add_torrent(add_torrent_params const& params);

include/libtorrent/torrent_flags.hpp

@@ -108,11 +108,10 @@ namespace torrent_flags {
 	// torrent for instance.
 	constexpr torrent_flags_t apply_ip_filter = 3_bit;
 
-	// specifies whether or not the torrent is to be started in a paused
-	// state. I.e. it won't connect to the tracker or any of the peers
-	// until it's resumed. This is typically a good way of avoiding race
-	// conditions when setting configuration options on torrents before
-	// starting them.
+	// specifies whether or not the torrent is paused. i.e. it won't connect to the tracker or any of the peers
+	// until it's resumed. Note that a paused torrent that also has the
+	// auto_managed flag set can be started at any time by libtorrent's queuing
+	// logic. See queuing_.
 	constexpr torrent_flags_t paused = 4_bit;
 
 	// If the torrent is auto-managed (``auto_managed``), the torrent
@@ -161,14 +160,14 @@ namespace torrent_flags {
 	// if the auto_manages flag is cleared and the paused flag is set on the torrent.
 	//
 	// Note that the torrent may transition into a downloading state while
-	// calling this function, and since the logic is edge triggered you may
+	// setting this flag, and since the logic is edge triggered you may
 	// miss the edge. To avoid this race, if the torrent already is in a
 	// downloading state when this call is made, it will trigger the
 	// stop-when-ready immediately.
 	//
 	// When the stop-when-ready logic fires, the flag is cleared. Any
 	// subsequent transitions between downloading and non-downloading states
-	// will not be affected, until this function is used to set it again.
+	// will not be affected, until this flag is set again.
 	//
 	// The behavior is more robust when setting this flag as part of adding
 	// the torrent. See add_torrent_params.

include/libtorrent/torrent_handle.hpp

@@ -585,8 +585,9 @@ namespace aux {
 		// ``unset_flags`` clears the specified flags, while leaving
 		// any other flags unchanged.
 		//
-		// The `seed_mode` flag is special, it can only be cleared by the
-		// `set_flags()` function, not set.
+		// The `seed_mode` flag is special, it can only be cleared once the
+		// torrent has been added, and it can only be set as part of the
+		// add_torrent_params flags, when adding the torrent.
 		torrent_flags_t flags() const;
 		void set_flags(torrent_flags_t flags, torrent_flags_t mask) const;
 		void set_flags(torrent_flags_t flags) const;
@@ -851,7 +852,7 @@ namespace aux {
 		// ================ start deprecation ============
 
 		// deprecated in 1.2
-
+		// use set_flags() and unset_flags() instead
 		TORRENT_DEPRECATED
 		void stop_when_ready(bool b) const;
 		TORRENT_DEPRECATED
@@ -899,7 +900,9 @@ namespace aux {
 		TORRENT_DEPRECATED
 		void set_ratio(float up_down_ratio) const;
 
-		// deprecated in 0.16. use status() instead
+		// deprecated in 0.16. use status() instead, and inspect the
+		// torrent_status::flags field. Alternatively, call flags() directly on
+		// the torrent_handle
 		TORRENT_DEPRECATED
 		bool is_seed() const;
 		TORRENT_DEPRECATED

include/libtorrent/torrent_info.hpp

@@ -234,7 +234,7 @@ namespace libtorrent {
 			return m_orig_files ? *m_orig_files : m_files;
 		}
 
-		// Renames a the file with the specified index to the new name. The new
+		// Renames the file with the specified index to the new name. The new
 		// filename is reflected by the ``file_storage`` returned by ``files()``
 		// but not by the one returned by ``orig_files()``.
 		//

src/torrent.cpp

@@ -6300,12 +6300,12 @@ bool is_downloading_state(int const st)
 
 		ret.flags = torrent_flags_t{};
 		if (m_sequential_download) ret.flags |= torrent_flags::sequential_download;
-		if (m_seed_mode ) ret.flags |= torrent_flags::seed_mode;
+		if (m_seed_mode) ret.flags |= torrent_flags::seed_mode;
 #ifndef TORRENT_DISABLE_SUPERSEEDING
 		if (m_super_seeding ) ret.flags |= torrent_flags::super_seeding;
 #endif
 		if (is_torrent_paused()) ret.flags |= torrent_flags::paused;
-		if (m_auto_managed ) ret.flags |= torrent_flags::auto_managed;
+		if (m_auto_managed) ret.flags |= torrent_flags::auto_managed;
 		if (m_stop_when_ready) ret.flags |= torrent_flags::stop_when_ready;
 
 		ret.added_time = m_added_time;