From 781c17363d804a0ea4038c2171be759773badda4 Mon Sep 17 00:00:00 2001 From: arvidn Date: Fri, 20 Mar 2020 13:13:46 +0100 Subject: [PATCH] improve documentation for a few torrent flags --- include/libtorrent/torrent_flags.hpp | 33 ++++++++++++++-------------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/include/libtorrent/torrent_flags.hpp b/include/libtorrent/torrent_flags.hpp index a71c9cbb0..15a812316 100644 --- a/include/libtorrent/torrent_flags.hpp +++ b/include/libtorrent/torrent_flags.hpp @@ -136,28 +136,29 @@ namespace torrent_flags { // updates when calling post_torrent_updates(). constexpr torrent_flags_t update_subscribe = 7_bit; - // sets the torrent into super seeding mode. If the torrent is not a - // seed, this flag has no effect. It has the same effect as calling - // ``torrent_handle::super_seeding(true)`` on the torrent handle - // immediately after adding it. + // sets the torrent into super seeding/initial seeding mode. If the torrent + // is not a seed, this flag has no effect. constexpr torrent_flags_t super_seeding = 8_bit; - // sets the sequential download state for the torrent. It has the same - // effect as calling ``torrent_handle::sequential_download(true)`` on - // the torrent handle immediately after adding it. + // sets the sequential download state for the torrent. In this mode the + // piece picker will pick pieces with low index numbers before pieces with + // high indices. The actual pieces that are picked depend on other factors + // still, such as which pieces a peer has and whether it is in parole mode + // or "prefer whole pieces"-mode. Sequential mode is not ideal for streaming + // media. For that, see set_piece_deadline() instead. constexpr torrent_flags_t sequential_download = 9_bit; - // When this flag is set, the - // torrent will *force stop* whenever it transitions from a - // non-data-transferring state into a data-transferring state (referred to - // as being ready to download or seed). This is useful for torrents that - // should not start downloading or seeding yet, but want to be made ready - // to do so. A torrent may need to have its files checked for instance, so - // it needs to be started and possibly queued for checking (auto-managed - // and started) but as soon as it's done, it should be stopped. + // When this flag is set, the torrent will *force stop* whenever it + // transitions from a non-data-transferring state into a data-transferring + // state (referred to as being ready to download or seed). This is useful + // for torrents that should not start downloading or seeding yet, but want + // to be made ready to do so. A torrent may need to have its files checked + // for instance, so it needs to be started and possibly queued for checking + // (auto-managed and started) but as soon as it's done, it should be + // stopped. // // *Force stopped* means auto-managed is set to false and it's paused. As - // if auto_manage(false) and pause() were called on the torrent. + // 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