From 903ac3b2683d79745543ba4f9f9299e92ac6f3db Mon Sep 17 00:00:00 2001 From: Arvid Norberg Date: Mon, 28 Apr 2014 04:46:33 +0000 Subject: [PATCH] reference documentation cleanup --- docs/gen_reference_doc.py | 32 ++- docs/manual-ref.html | 28 +- docs/reference-Alerts.html | 8 +- docs/reference-Bencoding.html | 50 ++-- docs/reference-Core.html | 112 ++++---- docs/reference-Create_Torrents.html | 8 +- docs/reference-Custom_Storage.html | 160 ++++++----- docs/reference-Error_Codes.html | 10 +- docs/reference-Plugins.html | 80 +++--- docs/reference-RSS.html | 10 +- docs/reference-Session.html | 325 ++++++++++++---------- docs/reference-Settings.html | 34 +-- docs/reference-Time.html | 6 +- docs/reference-Utility.html | 28 +- include/libtorrent/add_torrent_params.hpp | 277 +++++++++--------- include/libtorrent/alert.hpp | 26 +- include/libtorrent/bitfield.hpp | 2 +- include/libtorrent/identify_client.hpp | 15 +- include/libtorrent/storage.hpp | 150 +++++----- 19 files changed, 733 insertions(+), 628 deletions(-) diff --git a/docs/gen_reference_doc.py b/docs/gen_reference_doc.py index af68580b3..af69d56d2 100644 --- a/docs/gen_reference_doc.py +++ b/docs/gen_reference_doc.py @@ -146,12 +146,19 @@ def highlight_signature(s): # make the name of the function bold name2[-1] = '**' + name2[-1] + '** ' - name2[0] = name2[0].replace('*', '\\*') + + # if there is a return value, make sure we preserve pointer types + if len(name2) > 1: + name2[0] = name2[0].replace('*', '\\*') name[0] = ' '.join(name2) # we have to escape asterisks, since this is rendered into # a parsed literal in rst name[1] = name[1].replace('*', '\\*') + + # comments in signatures are italic + name[1] = name[1].replace('/\\*', '*/\\*') + name[1] = name[1].replace('\\*/', '\\*/*') return '('.join(name) def html_sanitize(s): @@ -756,25 +763,28 @@ def linkify_symbols(string): in_literal = True words = l.split(' ') - if len(words) == 1: - ret.append(l) - continue - for i in range(len(words)): # it's important to preserve leading # tabs, since that's relevant for # rst markup - leading_tabs = 0 - while leading_tabs < len(words[i]) and words[i][leading_tabs] == '\t': - leading_tabs += 1 + + leading = '' + w = words[i] + + if len(w) == 0: continue + + while len(w) > 0 and \ + w[0] in ['\t', ' ', '(', '[', '{']: + leading += w[0] + w = w[1:] # preserve commas and dots at the end - w = words[i].strip() + w = w.strip() trailing = '' if len(w) == 0: continue - while len(w) > 1 and (w[-1] == '.' or w[-1] == ',' or (w[-1] == ')' and w[-2:] != '()')): + while len(w) > 1 and w[-1] in ['.', ',', ')'] and w[-2:] != '()': trailing = w[-1] + trailing w = w[:-1] @@ -789,7 +799,7 @@ def linkify_symbols(string): if w in symbols: link_name = link_name.replace('-', ' ') # print ' found %s -> %s' % (w, link_name) - words[i] = (leading_tabs * '\t') + print_link(link_name, symbols[w]) + trailing + words[i] = leading + print_link(link_name, symbols[w]) + trailing ret.append(' '.join(words)) return '\n'.join(ret) diff --git a/docs/manual-ref.html b/docs/manual-ref.html index 20e5aff5a..aa9a8b40b 100644 --- a/docs/manual-ref.html +++ b/docs/manual-ref.html @@ -55,17 +55,17 @@

Table of contents

@@ -93,7 +93,7 @@ and s
  • handle updates to torrents, (see state_update_alert).
  • handle other alerts, (see alert).
  • query the session for information (see session::status()).
    • -
  • add and remove torrents from the session (remove_torrent())
    • +
  • add and remove torrents from the session (remove_torrent())
    • @@ -815,7 +815,7 @@ into the normal tit-for-tat mode of bittorrent, and will result in a long ramp-up time. The heuristic to mitigate this problem is to, for the first few pieces, pick random pieces rather than rare pieces. The threshold for when to leave this initial picker mode is determined by -session_settings::initial_picker_threshold.

    +session_settings::initial_picker_threshold.

    reverse order

    @@ -841,7 +841,7 @@ number of partial pieces is minimized (and hence the turn-around time for downloading a block until it can be uploaded to others is minimized). It also puts less stress on the disk cache, since fewer partial pieces need to be kept in the cache. Whether or not to enable this is controlled by -session_settings::prioritize_partial_pieces.

    +session_settings::prioritize_partial_pieces.

    The main benefit of not prioritizing partial pieces is that the rarest first algorithm gets to have more influence on which pieces are picked. The picker is more likely to truly pick the rarest piece, and hence improving the performance diff --git a/docs/reference-Alerts.html b/docs/reference-Alerts.html index 700b234ad..fe3fc3ea6 100644 --- a/docs/reference-Alerts.html +++ b/docs/reference-Alerts.html @@ -793,7 +793,7 @@ code indicating an error.

     struct scrape_failed_alert: tracker_alert
 {
-   **scrape_failed_alert** (torrent_handle const& h
+   scrape_failed_alert (torrent_handle const& h
       , std::string const& u
       , std::string const& m);
    virtual std::string message () const;
@@ -2364,7 +2364,7 @@ specifically the overload for looking up immutable items in the DHT.
    
 struct dht_immutable_item_alert: alert
 {
    virtual bool discardable () const;
-   **dht_immutable_item_alert** (sha1_hash const& t, entry const& i);
+   dht_immutable_item_alert (sha1_hash const& t, entry const& i);
    virtual std::string message () const;
 
    | alert::dht_notification;
@@ -2390,7 +2390,7 @@ specifically the overload for looking up mutable items in the DHT.
    
 
     struct dht_mutable_item_alert: alert
 {
-   **dht_mutable_item_alert** (boost::array<char, 32> k
+   dht_mutable_item_alert (boost::array<char, 32> k
       , boost::array<char, 64> sig
       , boost::uint64_t sequence
       , std::string const& s
@@ -2471,7 +2471,7 @@ salt and sequence number the item was stored under.
 
     struct i2p_alert : alert
 {
-   **i2p_alert** (error_code const& ec);
+   i2p_alert (error_code const& ec);
    virtual std::string message () const;
 
    const static int static_category = alert::error_notification;
diff --git a/docs/reference-Bencoding.html b/docs/reference-Bencoding.html
index 0b66d2b5c..9091aae5f 100644
--- a/docs/reference-Bencoding.html
+++ b/docs/reference-Bencoding.html
@@ -55,11 +55,11 @@
 
 
    Bencoding is a common representation in bittorrent used for
@@ -115,7 +115,7 @@ of the entry
 
     struct type_error: std::runtime_error
 {
-   **type_error** (const char* error);
+   type_error (const char* error);
 };
    @@ -129,11 +129,11 @@ or a string.

    class entry { data_type type () const; - **entry** (list_type const&); - **entry** (integer_type const&); - **entry** (dictionary_type const&); - **entry** (string_type const&); - **entry** (data_type t); + entry (list_type const&); + entry (integer_type const&); + entry (dictionary_type const&); + entry (string_type const&); + entry (data_type t); void operator= (string_type const&); void operator= (entry const&); void operator= (integer_type const&); @@ -181,10 +181,10 @@ data_type type () const;

    entry()

    -**entry** (list_type const&);
-**entry** (integer_type const&);
-**entry** (dictionary_type const&);
-**entry** (string_type const&);
+entry (list_type const&);
+entry (integer_type const&);
+entry (dictionary_type const&);
+entry (string_type const&);

    constructors directly from a specific type. The content of the argument is copied into the @@ -193,7 +193,7 @@ newly constructed

    entry()

    -**entry** (data_type t);
+entry (data_type t);

    construct an empty entry of the specified type. see data_type enum.

    @@ -209,7 +209,7 @@ void operator= (dictionary_type const&); void operator= (list_type const&);

    copies the structure of the right hand side into this -entry.

    +entry.

    @@ -273,7 +273,7 @@ void swap (entry& e);

    swaps the content of this with e.

    -
    +

    operator[]()

     entry& operator[] (std::string const& key);
@@ -372,22 +372,22 @@ would require copying the string.
    
 
     struct pascal_string
 {
-   **pascal_string** (char const* p, int l);
+   pascal_string (char const* p, int l);
    bool operator< (pascal_string const& rhs) const;
 
    int len;
    char const* ptr;
 };
 
    
-
    
+
    
 
    pascal_string()
    
 
    -**pascal_string** (char const* p, int l);
+pascal_string (char const* p, int l);
 
    
 
    construct a string pointing to the characters at p
 of length l characters. No NULL termination is required.
    
 
    
-
    
+
    
 
    operator<()
    
 
     bool operator< (pascal_string const& rhs) const;
@@ -460,7 +460,7 @@ struct lazy_entry
    };
 };
 
    
-
    
+
    
 
    type()
    
 
     entry_type_t type () const;
@@ -636,7 +636,7 @@ std::pair<char const*, int> data_section () const;
 
    returns pointers into the source buffer where
 this entry has its bencoded data
    
 
    
-
    
+
    
 
    swap()
    
 
     void swap (lazy_entry& e);
@@ -724,7 +724,7 @@ entry e = bdecode(buf, buf + data_size);
 
    If bdecode() encounters invalid encoded data in the range given to it
 it will throw libtorrent_exception.
    
 
    
-
    
+
    
 
    operator<<()
    
 
    Declared in "libtorrent/entry.hpp"
    
 
    diff --git a/docs/reference-Core.html b/docs/reference-Core.html
index 664c61896..16ffe8a25 100644
--- a/docs/reference-Core.html
+++ b/docs/reference-Core.html
@@ -55,15 +55,15 @@
 
 
    
@@ -78,8 +78,8 @@ this buffer has been released, buffer() will r
 
     struct disk_buffer_holder
 {
-   **disk_buffer_holder** (disk_buffer_pool& disk_pool, char* buf);
-   **~disk_buffer_holder** ();
+   disk_buffer_holder (disk_buffer_pool& disk_pool, char* buf);
+   ~disk_buffer_holder ();
    char* release ();
    char* get () const;
    void reset (char* buf = 0);
@@ -89,7 +89,7 @@ struct disk_buffer_holder
 
    
 
    disk_buffer_holder()
    
 
    -**disk_buffer_holder** (disk_buffer_pool& disk_pool, char* buf);
+disk_buffer_holder (disk_buffer_pool& disk_pool, char* buf);
 
    
 
    construct a buffer holder that will free the held buffer
 using a disk buffer pool directly (there's only one
@@ -98,7 +98,7 @@ disk_buffer_pool per 
 
    ~disk_buffer_holder()
    
 
    -**~disk_buffer_holder** ();
+~disk_buffer_holder ();
 
    
 
    frees any unreleased disk buffer held by this object
    
 
    
@@ -1011,7 +1011,7 @@ handle will remain valid between two calls.
    
 
     struct torrent_handle
 {
-   **torrent_handle** ();
+   torrent_handle ();
    void add_piece (int piece, char const* data, int flags = 0) const;
    void read_piece (int piece) const;
    bool have_piece (int piece) const;
@@ -1136,7 +1136,7 @@ struct torrent_handle
 
    
 
    torrent_handle()
    
 
    -**torrent_handle** ();
+torrent_handle ();
 
    
 
    constructs a torrent handle that does not refer to a torrent.
 i.e. is_valid() will return false.
    
@@ -1158,7 +1158,7 @@ instruct libtorrent to overwrite any data that may already have been
 downloaded with this data.
    
 
    Since the data is written asynchronously, you may know that is passed
 or failed the hash check by waiting for piece_finished_alert or
-hash_failed_alert.
    
+hash_failed_alert.
    
 
    
 
    
 
    read_piece()
    
@@ -1312,11 +1312,11 @@ libtorrent to use another list of trackers for this torrent, you can
 use replace_trackers() which takes a list of the same form as the
 one returned from trackers() and will replace it. If you want an
 immediate effect, you have to call force_reannounce(). See
-announce_entry.
    
+announce_entry.
    
 
    add_tracker() will look if the specified tracker is already in the
 set. If it is, it doesn't do anything. If it's not in the current set
 of trackers, it will insert it in the tier specified in the
-announce_entry.
    
+announce_entry.
    
 
    The updated set of trackers will be saved in the resume data, and when
 a torrent is started with resume data, the trackers from the resume
 data will replace the original ones.
    
@@ -1405,7 +1405,7 @@ all peers respectively. When a torrent is paused, it will however
 remember all share ratios to all peers and remember all potential (not
 connected) peers. Torrents may be paused automatically if there is a
 file error (e.g. disk full) or something similar. See
-file_error_alert.
    
+file_error_alert.
    
 
    To know if a torrent is paused or not, call
 torrent_handle::status() and inspect torrent_status::paused.
    
 
    The flags argument to pause can be set to
@@ -1490,10 +1490,10 @@ void save_resume_data (int flags = 0) const;
 entry. This entry is suitable for being bencoded. For more information
 about how fast-resume works, see fast resume.
    
 
    The flags argument is a bitmask of flags ORed together. see
-save_resume_flags_t
    
+save_resume_flags_t
    
 
    This operation is asynchronous, save_resume_data will return
 immediately. The resume data is delivered when it's done through an
-save_resume_data_alert.
    
+save_resume_data_alert.
    
 
    The fast resume data will be empty in the following cases:
    
 
    
 
      
@@ -1916,7 +1916,7 @@ void set_max_uploads (int max_uploads) const;
 at the same time on this torrent. If you set this to -1, there will be
 no limit. This defaults to infinite. The primary setting controlling
 this is the global unchoke slots limit, set by unchoke_slots_limit in
-session_settings.
      
+session_settings.
      
 
      max_uploads() returns the current settings.
      
 
 
    
@@ -2231,7 +2231,7 @@ torrent file (such as a magnet link or a URL).
 
    torrent_status
    
 
    Declared in "libtorrent/torrent_handle.hpp"
    
 
    holds a snapshot of the status of a torrent, as queried by
-torrent_handle::status().
    
+torrent_handle::status().
    
 
     struct torrent_status
 {
@@ -2326,7 +2326,7 @@ struct torrent_status
    sha1_hash info_hash;
 };
 
    
-
    
+
    
 
    operator==()
    
 
     bool operator== (torrent_status const& st) const;
@@ -2334,7 +2334,7 @@ bool operator== (torrent_status const& st) const;
 
    compres if the torrent status objects come from the same torrent. i.e.
 only the torrent_handle field is compared.
    
 
    
-
    
+
    
 
    enum state_t
    
 
    Declared in "libtorrent/torrent_handle.hpp"
    
 
@@ -2822,9 +2822,9 @@ relates to a specific torrent.
     struct announce_entry
 {
-   **announce_entry** (std::string const& u);
-   **~announce_entry** ();
-   **announce_entry** ();
+   announce_entry (std::string const& u);
+   ~announce_entry ();
+   announce_entry ();
    int next_announce_in () const;
    int min_announce_in () const;
    void reset ();
@@ -2865,9 +2865,9 @@ struct announce_entry
 
    
 
    announce_entry() ~announce_entry()
    
 
    -**announce_entry** (std::string const& u);
-**~announce_entry** ();
-**announce_entry** ();
+announce_entry (std::string const& u);
+~announce_entry ();
+announce_entry ();
 
    
 
    constructs a tracker announce entry with u as the URL.
    
 
@@ -2884,7 +2884,7 @@ allowed to force another tracker update with this tracker.
    
 
    If the last time this tracker was contacted failed, last_error is the error
 code describing what error occurred.
    
 
    
-
    
+
    
 
    reset()
    
 
     void reset ();
@@ -3047,15 +3047,15 @@ announces.
 
     class torrent_info : public intrusive_ptr_base<torrent_info>
 {
-   **torrent_info** (std::string const& filename, int flags = 0);
-   **torrent_info** (char const* buffer, int size, error_code& ec, int flags = 0);
-   **torrent_info** (sha1_hash const& info_hash, int flags = 0);
-   **torrent_info** (lazy_entry const& torrent_file, int flags = 0);
-   **torrent_info** (char const* buffer, int size, int flags = 0);
-   **torrent_info** (lazy_entry const& torrent_file, error_code& ec, int flags = 0);
-   **torrent_info** (torrent_info const& t, int flags = 0);
-   **torrent_info** (std::string const& filename, error_code& ec, int flags = 0);
-   **~torrent_info** ();
+   torrent_info (std::string const& filename, int flags = 0);
+   torrent_info (char const* buffer, int size, error_code& ec, int flags = 0);
+   torrent_info (sha1_hash const& info_hash, int flags = 0);
+   torrent_info (lazy_entry const& torrent_file, int flags = 0);
+   torrent_info (char const* buffer, int size, int flags = 0);
+   torrent_info (lazy_entry const& torrent_file, error_code& ec, int flags = 0);
+   torrent_info (torrent_info const& t, int flags = 0);
+   torrent_info (std::string const& filename, error_code& ec, int flags = 0);
+   ~torrent_info ();
    file_storage const& files () const;
    file_storage const& orig_files () const;
    void rename_file (int index, std::string const& new_filename);
@@ -3100,17 +3100,17 @@ class torrent_info : public intrusive_ptr_base<torrent_info>
    bool is_merkle_torrent () const;
 };
 
    
-
    
+
    
 
    torrent_info()
    
 
    -**torrent_info** (std::string const& filename, int flags = 0);
-**torrent_info** (char const* buffer, int size, error_code& ec, int flags = 0);
-**torrent_info** (sha1_hash const& info_hash, int flags = 0);
-**torrent_info** (lazy_entry const& torrent_file, int flags = 0);
-**torrent_info** (char const* buffer, int size, int flags = 0);
-**torrent_info** (lazy_entry const& torrent_file, error_code& ec, int flags = 0);
-**torrent_info** (torrent_info const& t, int flags = 0);
-**torrent_info** (std::string const& filename, error_code& ec, int flags = 0);
+torrent_info (std::string const& filename, int flags = 0);
+torrent_info (char const* buffer, int size, error_code& ec, int flags = 0);
+torrent_info (sha1_hash const& info_hash, int flags = 0);
+torrent_info (lazy_entry const& torrent_file, int flags = 0);
+torrent_info (char const* buffer, int size, int flags = 0);
+torrent_info (lazy_entry const& torrent_file, error_code& ec, int flags = 0);
+torrent_info (torrent_info const& t, int flags = 0);
+torrent_info (std::string const& filename, error_code& ec, int flags = 0);
 
    
 
    The constructor that takes an info-hash  will initialize the info-hash to the given value,
 but leave all other fields empty. This is used internally when downloading torrents without
@@ -3132,10 +3132,10 @@ always throw if an error occurs. These overloads are not available when building
 exception support.
    
 
    The flags argument is currently unused.
    
 
    
-
    
+
    
 
    ~torrent_info()
    
 
    -**~torrent_info** ();
+~torrent_info ();
 
    
 
    frees all storage associated with this torrent_info object
    
 
@@ -3157,7 +3157,7 @@ names. Filename may be chaged using file_storage object, see the separate document on how
 to create torrents.
    
 
    
-
    
+
    
 
    rename_file()
    
 
     void rename_file (int index, std::string const& new_filename);
@@ -3242,7 +3242,7 @@ the piece index as argument and gives you the exact size of that piece. It will
 be the same as piece_length() except in the case of the last piece, which may
 be smaller.
    
 
    
-
    
+
    
 
    info_hash()
    
 
     const sha1_hash& info_hash () const;
@@ -3289,7 +3289,7 @@ std::string ssl_cert () const;
 torrent. Otherwise returns an empty string. The certificate is
 the the public certificate in x509 format.
    
 
    
-
    
+
    
 
    is_valid()
    
 
     bool is_valid () const;
@@ -3402,7 +3402,7 @@ lazy_entry const* info (char const* key) const;
 It can be used to access extension values put in the .torrent file. If the specified
 key cannot be found, it returns NULL.
    
 
    
-
    
+
    
 
    swap()
    
 
     void swap (torrent_info& ti);
diff --git a/docs/reference-Create_Torrents.html b/docs/reference-Create_Torrents.html
index d94e0f119..fab844c72 100644
--- a/docs/reference-Create_Torrents.html
+++ b/docs/reference-Create_Torrents.html
@@ -103,8 +103,8 @@ the torrent. The 
 struct create_torrent
 {
-   **create_torrent** (torrent_info const& ti);
-   **create_torrent** (file_storage& fs, int piece_size = 0
+   create_torrent (torrent_info const& ti);
+   create_torrent (file_storage& fs, int piece_size = 0
       , int pad_file_limit = -1, int flags = optimize, int alignment = 0x4000);
    entry generate () const;
    file_storage const& files () const;
@@ -137,8 +137,8 @@ struct create_torrent
 
    
 
    create_torrent()
    
 
    -**create_torrent** (torrent_info const& ti);
-**create_torrent** (file_storage& fs, int piece_size = 0
+create_torrent (torrent_info const& ti);
+create_torrent (file_storage& fs, int piece_size = 0
       , int pad_file_limit = -1, int flags = optimize, int alignment = 0x4000);
 
    
 
    The piece_size is the size of each piece in bytes. It must
diff --git a/docs/reference-Custom_Storage.html b/docs/reference-Custom_Storage.html
index 33fd5a219..d13e37ae7 100644
--- a/docs/reference-Custom_Storage.html
+++ b/docs/reference-Custom_Storage.html
@@ -55,14 +55,24 @@
 
    
-
    This is an example storage implementation that stores all pieces in a std::map,
-i.e. in RAM. It's not necessarily very useful in practice, but illustrates the
-basics of implementing a custom storage.
    
+
    libtorrent provides a customization point for storage of data. By default,
+(default_storage) downloaded files are saved to disk according with the
+general conventions of bittorrent clients, mimicing the original file layout
+when the torrent was created. The libtorrent user may define a custom
+storage to store piece data in a different way.
    
+
    A custom storage implementation must derive from and implement the
+storage_interface. You must also provide a function that constructs the
+custom storage object and provide this function to the add_torrent() call
+via add_torrent_params. Either passed in to the constructor or by setting
+the add_torrent_params::storage field.
    
+
    This is an example storage implementation that stores all pieces in a
+std::map, i.e. in RAM. It's not necessarily very useful in practice, but
+illustrates the basics of implementing a custom storage.
    
 
     struct temp_storage : storage_interface
 {
@@ -139,8 +149,8 @@ may be windows where more file handles are open.
    
 
     struct file_pool : boost::noncopyable
 {
-   **~file_pool** ();
-   **file_pool** (int size = 40);
+   ~file_pool ();
+   file_pool (int size = 40);
    boost::intrusive_ptr<file> open_file (void* st, std::string const& p
       , int file_index, file_storage const& fs, int m, error_code& ec);
    void release (void* st);
@@ -153,8 +163,8 @@ struct file_pool : boost::noncopyable
 
    
 
    ~file_pool() file_pool()
    
 
    -**~file_pool** ();
-**file_pool** (int size = 40);
+~file_pool ();
+file_pool (int size = 40);
 
    
 
    size specifies the number of allowed files handles
 to hold open at any given time.
    
@@ -200,23 +210,24 @@ by the libtorrent/storage.hpp"
    
 
    The storage interface is a pure virtual class that can be implemented to
 customize how and where data for a torrent is stored. The default storage
-implementation uses regular files in the filesystem, mapping the files in the
-torrent in the way one would assume a torrent is saved to disk. Implementing
-your own storage interface makes it possible to store all data in RAM, or in
-some optimized order on disk (the order the pieces are received for instance),
-or saving multifile torrents in a single file in order to be able to take
-advantage of optimized disk-I/O.
    
-
    It is also possible to write a thin class that uses the default storage but
-modifies some particular behavior, for instance encrypting the data before
-it's written to disk, and decrypting it when it's read again.
    
+implementation uses regular files in the filesystem, mapping the files in
+the torrent in the way one would assume a torrent is saved to disk.
+Implementing your own storage interface makes it possible to store all
+data in RAM, or in some optimized order on disk (the order the pieces are
+received for instance), or saving multifile torrents in a single file in
+order to be able to take advantage of optimized disk-I/O.
    
+
    It is also possible to write a thin class that uses the default storage
+but modifies some particular behavior, for instance encrypting the data
+before it's written to disk, and decrypting it when it's read again.
    
 
    The storage interface is based on slots, each slot is 'piece_size' number
 of bytes. All access is done by writing and reading whole or partial
 slots. One slot is one piece in the torrent, but the data in the slot
 does not necessarily correspond to the piece with the same index (in
 compact allocation mode it won't).
    
-
    libtorrent comes with two built-in storage implementations; default_storage
-and disabled_storage. Their constructor functions are called default_storage_constructor()
-and disabled_storage_constructor respectively. The disabled storage does
+
    libtorrent comes with two built-in storage implementations;
+default_storage and disabled_storage. Their constructor functions
+are called default_storage_constructor() and
+disabled_storage_constructor respectively. The disabled storage does
 just what it sounds like. It throws away data that's written, and it
 reads garbage. It's useful mostly for benchmarking and profiling purpose.
    
 
    @@ -254,9 +265,10 @@ struct storage_interface
 
     virtual bool initialize (bool allocate_files) = 0;
 
    
-
    This function is called when the storage is to be initialized. The default storage
-will create directories and empty files at this point. If allocate_files is true,
-it will also ftruncate all files to their target size.
    
+
    This function is called when the storage is to be initialized. The
+default storage will create directories and empty files at this point.
+If allocate_files is true, it will also ftruncate all files to
+their target size.
    
 
    Returning true indicates an error occurred.
    
 
    
 
    
@@ -264,9 +276,10 @@ it will also ftruncate all files to their targ
 
     virtual bool has_any_file () = 0;
 
    
-
    This function is called when first checking (or re-checking) the storage for a torrent.
-It should return true if any of the files that is used in this storage exists on disk.
-If so, the storage will be checked for existing pieces before starting the download.
    
+
    This function is called when first checking (or re-checking) the
+storage for a torrent. It should return true if any of the files that
+is used in this storage exists on disk. If so, the storage will be
+checked for existing pieces before starting the download.
    
 
    
 
    
 
    set_file_priority()
    
@@ -282,35 +295,37 @@ virtual void set_file_priority (std::vector<boost::uint8_t&g
 virtual int writev (file::iovec_t const* bufs, int slot, int offset, int num_bufs, int flags = file::random_access);
 virtual int readv (file::iovec_t const* bufs, int slot, int offset, int num_bufs, int flags = file::random_access);
 
    
-
    These functions should read or write the data in or to the given slot at the given offset.
-It should read or write num_bufs buffers sequentially, where the size of each buffer
-is specified in the buffer array bufs. The file::iovec_t type has the following members:
    
+
    These functions should read or write the data in or to the given
+slot at the given offset. It should read or write num_bufs
+buffers sequentially, where the size of each buffer is specified in
+the buffer array bufs. The file::iovec_t type has the following
+members:
    
 
    -struct iovec_t
-{
-        void* iov_base;
-        size_t iov_len;
-};
+struct iovec_t { void* iov_base; size_t iov_len; };
 
    
-
    The return value is the number of bytes actually read or written, or -1 on failure. If
-it returns -1, the error code is expected to be set to
    
-
    Every buffer in bufs can be assumed to be page aligned and be of a page aligned size,
-except for the last buffer of the torrent. The allocated buffer can be assumed to fit a
-fully page aligned number of bytes though. This is useful when reading and writing the
-last piece of a file in unbuffered mode.
    
-
    The offset is aligned to 16 kiB boundries  most of the time, but there are rare
-exceptions when it's not. Specifically if the read cache is disabled/or full and a
-client requests unaligned data, or the file itself is not aligned in the torrent.
-Most clients request aligned data.
    
+
    The return value is the number of bytes actually read or written, or
+-1 on failure. If it returns -1, the error code is expected to be set
+to
    
+
    Every buffer in bufs can be assumed to be page aligned and be of a
+page aligned size, except for the last buffer of the torrent. The
+allocated buffer can be assumed to fit a fully page aligned number of
+bytes though. This is useful when reading and writing the last piece
+of a file in unbuffered mode.
    
+
    The offset is aligned to 16 kiB boundries  most of the time, but
+there are rare exceptions when it's not. Specifically if the read
+cache is disabled/or full and a client requests unaligned data, or the
+file itself is not aligned in the torrent. Most clients request
+aligned data.
    
 
    
 
    
 
    hint_read()
    
 
     virtual void hint_read (int, int, int);
 
    
-
    This function is called when a read job is queued. It gives the storage wrapper an
-opportunity to hint the operating system about this coming read. For instance, the
-storage may call posix_fadvise(POSIX_FADV_WILLNEED) or fcntl(F_RDADVISE).
    
+
    This function is called when a read job is queued. It gives the
+storage wrapper an opportunity to hint the operating system about this
+coming read. For instance, the storage may call
+posix_fadvise(POSIX_FADV_WILLNEED) or fcntl(F_RDADVISE).
    
 
    
 
    
 
    read()
    
@@ -339,20 +354,21 @@ byte at offset offset in slot 
 virtual int sparse_end (int start) const;
 
    
-
    This function is optional. It is supposed to return the first piece, starting at
-start that is fully contained within a data-region on disk (i.e. non-sparse
-region). The purpose of this is to skip parts of files that can be known to contain
-zeros when checking files.
    
+
    This function is optional. It is supposed to return the first piece,
+starting at start that is fully contained within a data-region on
+disk (i.e. non-sparse region). The purpose of this is to skip parts of
+files that can be known to contain zeros when checking files.
    
 
    
 
    
 
    move_storage()
    
 
     virtual int move_storage (std::string const& save_path, int flags) = 0;
 
    
-
    This function should move all the files belonging to the storage to the new save_path.
-The default storage moves the single file or the directory of the torrent.
    
-
    Before moving the files, any open file handles may have to be closed, like
-release_files().
    
+
    This function should move all the files belonging to the storage to
+the new save_path. The default storage moves the single file or the
+directory of the torrent.
    
+
    Before moving the files, any open file handles may have to be closed,
+like release_files().
    
 
    returns one of:
 | no_error = 0
 | need_full_check = -1
@@ -396,9 +412,10 @@ efficient than reading and writing the data.
    
 
     virtual bool swap_slots (int slot1, int slot2) = 0;
 
    
-
    This function should swap the data in slot1 and slot2. The default
-storage uses a scratch buffer to read the data into, then moving the other
-slot and finally writing back the temporary slot's data
    
+
    This function should swap the data in slot1 and slot2. The
+default storage uses a scratch buffer to read the data into, then
+moving the other slot and finally writing back the temporary slot's
+data
    
 
    This is only used in compact mode.
    
 
    Returning true indicates an error occurred.
    
 
    
@@ -408,8 +425,8 @@ slot and finally writing back the temporary slot's data
    
 virtual bool swap_slots3 (int slot1, int slot2, int slot3) = 0;
 
    
 
    This function should do a 3-way swap, or shift of the slots. slot1
-should move to slot2, which should be moved to slot3 which in turn
-should be moved to slot1.
    
+should move to slot2, which should be moved to slot3 which in
+turn should be moved to slot1.
    
 
    This is only used in compact mode.
    
 
    Returning true indicates an error occurred.
    
 
    
@@ -436,10 +453,11 @@ virtual bool rename_file (int index, std::string const& new
 
     virtual bool delete_files () = 0;
 
    
-
    This function should delete all files and directories belonging to this storage.
    
+
    This function should delete all files and directories belonging to
+this storage.
    
 
    Returning true indicates an error occurred.
    
-
    The disk_buffer_pool is used to allocate and free disk buffers. It has the
-following members:
    
+
    The disk_buffer_pool is used to allocate and free disk buffers. It
+has the following members:
    
 
     struct disk_buffer_pool : boost::noncopyable
 {
@@ -500,13 +518,13 @@ to the storage
    
 
    
 
    default_storage
    
 
    Declared in "libtorrent/storage.hpp"
    
-
    The default implementation of storage_interface. Behaves as a normal bittorrent client.
-It is possible to derive from this class in order to override some of its behavior, when
-implementing a custom storage.
    
+
    The default implementation of storage_interface. Behaves as a normal
+bittorrent client. It is possible to derive from this class in order to
+override some of its behavior, when implementing a custom storage.
    
 
     class default_storage : public storage_interface, boost::noncopyable
 {
-   **default_storage** (file_storage const& fs, file_storage const* mapped
+   default_storage (file_storage const& fs, file_storage const* mapped
       , std::string const& path, file_pool& fp
       , std::vector<boost::uint8_t> const& file_prio);
    bool move_slot (int src_slot, int dst_slot);
@@ -531,10 +549,10 @@ class default_storage : public storage_interface, boost::noncopyable
    file_storage const& files () const;
 };
 
    
-
    
+
    
 
    default_storage()
    
 
    -**default_storage** (file_storage const& fs, file_storage const* mapped
+default_storage (file_storage const& fs, file_storage const* mapped
       , std::string const& path, file_pool& fp
       , std::vector<boost::uint8_t> const& file_prio);
 
    
diff --git a/docs/reference-Error_Codes.html b/docs/reference-Error_Codes.html
index db19e6eb5..d223f622c 100644
--- a/docs/reference-Error_Codes.html
+++ b/docs/reference-Error_Codes.html
@@ -55,7 +55,7 @@
 
 
    
@@ -66,7 +66,7 @@ struct libtorrent_exception: std::exception
 {
    error_code error () const;
    virtual ~libtorrent_exception () throw();
-   **libtorrent_exception** (error_code const& s);
+   libtorrent_exception (error_code const& s);
    virtual const char* what () const throw();
 };
 
    
@@ -216,7 +216,7 @@ matched the info-hash, but failed to be parsed
 
    
+session
 
@@ -918,7 +918,7 @@ URL. i.e. it doesn't contain "announce.
 
    
 
    duplicate_torrent
 19
 There's already a torrent with that info-hash added to the
-session
    
 
    invalid_torrent_handle
 20
    
 
    
 
    
-
    
+
    
 
    enum error_code_enum
    
 
    Declared in "libtorrent/lazy_entry.hpp"
    
 
@@ -1036,7 +1036,7 @@ URL. i.e. it doesn't contain "announce.
    
 
 
    
 
    
-
    
+
    
 
    enum error_code_enum
    
 
    Declared in "libtorrent/upnp.hpp"
    
 
diff --git a/docs/reference-Plugins.html b/docs/reference-Plugins.html
index d19442250..4d3a2f84a 100644
--- a/docs/reference-Plugins.html
+++ b/docs/reference-Plugins.html
@@ -240,15 +240,15 @@ ability to change or override the default libtorrent behavior.
    
 struct torrent_plugin
 {
    virtual boost::shared_ptr<peer_plugin> new_connection (peer_connection*);
-   virtual void on_piece_pass (int /*index*/);
-   virtual void on_piece_failed (int /*index*/);
+   virtual void on_piece_pass (int /*index*/);
+   virtual void on_piece_failed (int /*index*/);
    virtual void tick ();
    virtual bool on_resume ();
    virtual bool on_pause ();
    virtual void on_files_checked ();
-   virtual void on_state (int /*s*/);
+   virtual void on_state (int /*s*/);
    virtual void on_add_peer (tcp::endpoint const&,
-      int /*src*/, int /*flags*/);
+      int /*src*/, int /*flags*/);
 };
 
    
@@ -273,8 +273,8 @@ use weak_ptr.
    
 
    
 
    on_piece_failed() on_piece_pass()
    
 
    -virtual void on_piece_pass (int /*index*/);
-virtual void on_piece_failed (int /*index*/);
+virtual void on_piece_pass (int /*index*/);
+virtual void on_piece_failed (int /*index*/);
 
    
 
    These hooks are called when a piece passes the hash check or fails the hash
 check, respectively. The index is the piece index that was downloaded.
@@ -320,7 +320,7 @@ can start downloading.
    
 
    
 
    on_state()
    
 
    -virtual void on_state (int /*s*/);
+virtual void on_state (int /*s*/);
 
    
 
    called when the torrent changes state
 the state is one of torrent_status::state_t
@@ -330,7 +330,7 @@ enum members
    
 
    on_add_peer()
    
 
     virtual void on_add_peer (tcp::endpoint const&,
-      int /*src*/, int /*flags*/);
+      int /*src*/, int /*flags*/);
 
    
 
    called every time a new peer is added to the peer list.
 This is before the peer is connected to. For flags, see
@@ -354,33 +354,33 @@ struct peer_plugin
 {
    virtual char const* type () const;
    virtual void add_handshake (entry&);
-   virtual void on_disconnect (error_code const& /*ec*/);
+   virtual void on_disconnect (error_code const& /*ec*/);
    virtual void on_connected ();
-   virtual bool on_handshake (char const* /*reserved_bits*/);
+   virtual bool on_handshake (char const* /*reserved_bits*/);
    virtual bool on_extension_handshake (lazy_entry const&);
-   virtual bool on_have (int /*index*/);
-   virtual bool on_bitfield (bitfield const& /*bitfield*/);
+   virtual bool on_have (int /*index*/);
+   virtual bool on_bitfield (bitfield const& /*bitfield*/);
    virtual bool on_have_all ();
    virtual bool on_reject (peer_request const&);
    virtual bool on_request (peer_request const&);
    virtual bool on_unchoke ();
    virtual bool on_interested ();
-   virtual bool on_allowed_fast (int /*index*/);
+   virtual bool on_allowed_fast (int /*index*/);
    virtual bool on_have_none ();
    virtual bool on_choke ();
    virtual bool on_not_interested ();
-   virtual bool on_piece (peer_request const& /*piece*/
-      , disk_buffer_holder& /*data*/);
-   virtual bool on_suggest (int /*index*/);
+   virtual bool on_piece (peer_request const& /*piece*/
+      , disk_buffer_holder& /*data*/);
+   virtual bool on_suggest (int /*index*/);
    virtual bool on_cancel (peer_request const&);
-   virtual bool on_dont_have (int /*index*/);
-   virtual bool can_disconnect (error_code const& /*ec*/);
-   virtual bool on_extended (int /*length*/, int /*msg*/,
-      buffer::const_interval /*body*/);
-   virtual bool on_unknown_message (int /*length*/, int /*msg*/,
-      buffer::const_interval /*body*/);
-   virtual void on_piece_pass (int /*index*/);
-   virtual void on_piece_failed (int /*index*/);
+   virtual bool on_dont_have (int /*index*/);
+   virtual bool can_disconnect (error_code const& /*ec*/);
+   virtual bool on_extended (int /*length*/, int /*msg*/,
+      buffer::const_interval /*body*/);
+   virtual bool on_unknown_message (int /*length*/, int /*msg*/,
+      buffer::const_interval /*body*/);
+   virtual void on_piece_pass (int /*index*/);
+   virtual void on_piece_failed (int /*index*/);
    virtual void tick ();
    virtual bool write_request (peer_request const&);
 };
@@ -404,7 +404,7 @@ this is not called for web seeds
    
 
    
 
    on_disconnect()
    
 
    -virtual void on_disconnect (error_code const& /*ec*/);
+virtual void on_disconnect (error_code const& /*ec*/);
 
    
 
    called when the peer is being disconnected.
    
 
    
@@ -421,7 +421,7 @@ called.
    
 
    
 
    on_handshake()
    
 
    -virtual bool on_handshake (char const* /*reserved_bits*/);
+virtual bool on_handshake (char const* /*reserved_bits*/);
 
    
 
    this is called when the initial BT handshake is received. Returning false
 means that the other end doesn't support this extension and will remove
@@ -456,22 +456,22 @@ this is not called for web seeds
    
 
    
 
    on_bitfield() on_have_none() on_suggest() on_unchoke() on_cancel() on_have() on_choke() on_piece() on_request() on_reject() on_not_interested() on_interested() on_allowed_fast() on_have_all() on_dont_have()
    
 
    -virtual bool on_have (int /*index*/);
-virtual bool on_bitfield (bitfield const& /*bitfield*/);
+virtual bool on_have (int /*index*/);
+virtual bool on_bitfield (bitfield const& /*bitfield*/);
 virtual bool on_have_all ();
 virtual bool on_reject (peer_request const&);
 virtual bool on_request (peer_request const&);
 virtual bool on_unchoke ();
 virtual bool on_interested ();
-virtual bool on_allowed_fast (int /*index*/);
+virtual bool on_allowed_fast (int /*index*/);
 virtual bool on_have_none ();
 virtual bool on_choke ();
 virtual bool on_not_interested ();
-virtual bool on_piece (peer_request const& /*piece*/
-      , disk_buffer_holder& /*data*/);
-virtual bool on_suggest (int /*index*/);
+virtual bool on_piece (peer_request const& /*piece*/
+      , disk_buffer_holder& /*data*/);
+virtual bool on_suggest (int /*index*/);
 virtual bool on_cancel (peer_request const&);
-virtual bool on_dont_have (int /*index*/);
+virtual bool on_dont_have (int /*index*/);
 
    
 
    returning true from any of the message handlers
 indicates that the plugin has handeled the message.
@@ -482,7 +482,7 @@ handler.
    
 
    
 
    can_disconnect()
    
 
    -virtual bool can_disconnect (error_code const& /*ec*/);
+virtual bool can_disconnect (error_code const& /*ec*/);
 
    
 
    called when libtorrent think this peer should be disconnected.
 if the plugin returns false, the peer will not be disconnected.
    
@@ -490,8 +490,8 @@ if the plugin
 
    
 
    on_extended()
    
 
    -virtual bool on_extended (int /*length*/, int /*msg*/,
-      buffer::const_interval /*body*/);
+virtual bool on_extended (int /*length*/, int /*msg*/,
+      buffer::const_interval /*body*/);
 
    
 
    called when an extended message is received. If returning true,
 the message is not processed by any other plugin and if false
@@ -502,8 +502,8 @@ this is not called for web seeds
    
 
    
 
    on_unknown_message()
    
 
    -virtual bool on_unknown_message (int /*length*/, int /*msg*/,
-      buffer::const_interval /*body*/);
+virtual bool on_unknown_message (int /*length*/, int /*msg*/,
+      buffer::const_interval /*body*/);
 
    
 
    this is not called for web seeds
    
 
@@ -511,8 +511,8 @@ virtual bool on_unknown_message (int /*length*/, int /*msg*/,
 
    
 
    on_piece_failed() on_piece_pass()
    
 
    -virtual void on_piece_pass (int /*index*/);
-virtual void on_piece_failed (int /*index*/);
+virtual void on_piece_pass (int /*index*/);
+virtual void on_piece_failed (int /*index*/);
 
    
 
    called when a piece that this peer participated in either
 fails or passes the hash_check
    
diff --git a/docs/reference-RSS.html b/docs/reference-RSS.html
index f9534b756..ae879218d 100644
--- a/docs/reference-RSS.html
+++ b/docs/reference-RSS.html
@@ -69,8 +69,8 @@ a feed of torrents.
    
 
     struct feed_item
 {
-   **feed_item** ();
-   **~feed_item** ();
+   feed_item ();
+   ~feed_item ();
 
    std::string url;
    std::string uuid;
@@ -119,7 +119,7 @@ after adding the feed
    
 
     struct feed_settings
 {
-   **feed_settings** ();
+   feed_settings ();
 
    std::string url;
    bool auto_download;
@@ -173,7 +173,7 @@ calling 
 struct feed_status
 {
-   **feed_status** ();
+   feed_status ();
 
    std::string url;
    std::string title;
@@ -240,7 +240,7 @@ default ttl, or the ttl specified by the feed.
 
     struct feed_handle
 {
-   **feed_handle** ();
+   feed_handle ();
    void update_feed ();
    feed_status get_feed_status () const;
    void set_settings (feed_settings const& s);
diff --git a/docs/reference-Session.html b/docs/reference-Session.html
index 093286531..9d0e0a0c8 100644
--- a/docs/reference-Session.html
+++ b/docs/reference-Session.html
@@ -55,39 +55,42 @@
 
 
    
 
    add_torrent_params
    
 
    Declared in "libtorrent/add_torrent_params.hpp"
    
-
    The add_torrent_params is a parameter pack for adding torrents to a session.
-The key fields when adding a torrent are:
    
+
    The add_torrent_params is a parameter pack for adding torrents to a
+session. The key fields when adding a torrent are:
    
 
      
 
    • ti - when you have a .torrent file
      • 
 
    • url - when you have a magnet link or http URL to the .torrent file
      • 
-
    • info_hash - when all you have is an info-hash (this is similar to a magnet link)
      • 
+
    • info_hash - when all you have is an info-hash (this is similar to a
+magnet link)
      • 
 
    
-
    one of those fields need to be set. Another mandatory field is save_path.
-The add_torrent_params object is passed into one of the session::add_torrent()
-overloads or session::async_add_torrent().
    
-
    If you only specify the info-hash, the torrent file will be downloaded from peers,
-which requires them to support the metadata extension. For the metadata extension
-to work, libtorrent must be built with extensions enabled (TORRENT_DISABLE_EXTENSIONS must not be
-defined). It also takes an optional name argument. This may be left empty in case no
-name should be assigned to the torrent. In case it's not, the name is used for
-the torrent as long as it doesn't have metadata. See torrent_handle::name.
    
+
    one of those fields need to be set. Another mandatory field is
+save_path. The add_torrent_params object is passed into one of the
+session::add_torrent() overloads or session::async_add_torrent().
    
+
    If you only specify the info-hash, the torrent file will be downloaded
+from peers, which requires them to support the metadata extension. For
+the metadata extension to work, libtorrent must be built with extensions
+enabled (TORRENT_DISABLE_EXTENSIONS must not be defined). It also
+takes an optional name argument. This may be left empty in case no
+name should be assigned to the torrent. In case it's not, the name is
+used for the torrent as long as it doesn't have metadata. See
+torrent_handle::name.
    
 
     struct add_torrent_params
 {
-   **add_torrent_params** (storage_constructor_type sc = default_storage_constructor);
+   add_torrent_params (storage_constructor_type sc = default_storage_constructor);
 
    enum flags_t
    {
@@ -132,20 +135,20 @@ struct add_torrent_params
 
    
 
    add_torrent_params()
    
 
    -**add_torrent_params** (storage_constructor_type sc = default_storage_constructor);
+add_torrent_params (storage_constructor_type sc = default_storage_constructor);
 
    
-
    The constructor can be used to initialize the storage constructor, which determines
-the storage mechanism for the downloaded or seeding data for the torrent. For more
-information, see the storage field.
    
+
    The constructor can be used to initialize the storage constructor,
+which determines the storage mechanism for the downloaded or seeding
+data for the torrent. For more information, see the storage field.
    
 
    
 
    
 
    enum flags_t
    
 
    Declared in "libtorrent/add_torrent_params.hpp"
    
 
    
 
    ---+++
@@ -156,84 +159,99 @@ information, see the storage field.
    
-
-
-
+default all torrents are subject to filtering by the IP filter
+(i.e. this flag is set by default). This is useful if certain
+torrents needs to be excempt for some reason, being an auto-update
+torrent for instance.
+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.
-
@@ -243,7 +261,8 @@ by setting override_resume_data.
    
+resume data should be added to the trackers in the torrent or
+replace the trackers.
@@ -252,16 +271,16 @@ updates when calling torrent_handle::super_seeding(true) on the torrent handle immediately
-after adding it.
+
-
+
    
 






 
 
 
    name
 
    
 
    flag_seed_mode
 1
    If flag_seed_mode is set, libtorrent will assume that all files are present
-for this torrent and that they all match the hashes in the torrent file. Each time
-a peer requests to download a block, the piece is verified against the hash, unless
-it has been verified already. If a hash fails, the torrent will automatically leave
-the seed mode and recheck all the files. The use case for this mode is if a torrent
-is created and seeded, or if the user already know that the files are complete, this
-is a way to avoid the initial file checks, and significantly reduce the startup time.
    
-
    Setting flag_seed_mode on a torrent without metadata (a .torrent file) is a no-op
-and will be ignored.
    
-
    If resume data is passed in with this torrent, the seed mode saved in there will
-override the seed mode you set here.
    
+
    If flag_seed_mode is set, libtorrent will assume that all files
+are present for this torrent and that they all match the hashes in
+the torrent file. Each time a peer requests to download a block,
+the piece is verified against the hash, unless it has been verified
+already. If a hash fails, the torrent will automatically leave the
+seed mode and recheck all the files. The use case for this mode is
+if a torrent is created and seeded, or if the user already know
+that the files are complete, this is a way to avoid the initial
+file checks, and significantly reduce the startup time.
    
+
    Setting flag_seed_mode on a torrent without metadata (a
+.torrent file) is a no-op and will be ignored.
    
+
    If resume data is passed in with this torrent, the seed mode saved
+in there will override the seed mode you set here.
    
     		
 
    
 
    flag_override_resume_data
 2
    If flag_override_resume_data is set, the paused and auto_managed
-state of the torrent are not loaded from the resume data, but the states requested
-by the flags in add_torrent_params will override them.
    
-
    If you pass in resume data, the paused state of the torrent when the resume data
-was saved will override the paused state you pass in here. You can override this
-by setting flag_override_resume_data.
    
+
    If flag_override_resume_data is set, the paused and
+auto_managed state of the torrent are not loaded from the
+resume data, but the states requested by the flags in
+add_torrent_params will override them.
    
+
    If you pass in resume data, the paused state of the torrent when
+the resume data was saved will override the paused state you pass
+in here. You can override this by setting
+flag_override_resume_data.
    
     		
 
    
 
    flag_upload_mode
 4
    If flag_upload_mode is set, the torrent will be initialized in upload-mode,
-which means it will not make any piece requests. This state is typically entered
-on disk I/O errors, and if the torrent is also auto managed, it will be taken out
-of this state periodically. This mode can be used to avoid race conditions when
-adjusting priorities of pieces before allowing the torrent to start downloading.
    
-
    If the torrent is auto-managed (flag_auto_managed), the torrent will eventually
-be taken out of upload-mode, regardless of how it got there. If it's important to
-manually control when the torrent leaves upload mode, don't make it auto managed.
    
+
    If flag_upload_mode is set, the torrent will be initialized in
+upload-mode, which means it will not make any piece requests. This
+state is typically entered on disk I/O errors, and if the torrent
+is also auto managed, it will be taken out of this state
+periodically. This mode can be used to avoid race conditions when
+adjusting priorities of pieces before allowing the torrent to start
+downloading.
    
+
    If the torrent is auto-managed (flag_auto_managed), the torrent
+will eventually be taken out of upload-mode, regardless of how it
+got there. If it's important to manually control when the torrent
+leaves upload mode, don't make it auto managed.
    
     		
 
    
 
    flag_share_mode
 8
 
    determines if the torrent should be added in share mode or not.
-Share mode indicates that we are not interested in downloading the torrent, but
-merley want to improve our share ratio (i.e. increase it). A torrent started in
-share mode will do its best to never download more than it uploads to the swarm.
-If the swarm does not have enough demand for upload capacity, the torrent will
-not download anything. This mode is intended to be safe to add any number of torrents
-to, without manual screening, without the risk of downloading more than is uploaded.
    
-
    A torrent in share mode sets the priority to all pieces to 0, except for the pieces
-that are downloaded, when pieces are decided to be downloaded. This affects the progress
-bar, which might be set to "100% finished" most of the time. Do not change file or piece
+Share mode indicates that we are not interested in downloading the
+torrent, but merley want to improve our share ratio (i.e. increase
+it). A torrent started in share mode will do its best to never
+download more than it uploads to the swarm. If the swarm does not
+have enough demand for upload capacity, the torrent will not
+download anything. This mode is intended to be safe to add any
+number of torrents to, without manual screening, without the risk
+of downloading more than is uploaded.
    
+
    A torrent in share mode sets the priority to all pieces to 0,
+except for the pieces that are downloaded, when pieces are decided
+to be downloaded. This affects the progress bar, which might be set
+to "100% finished" most of the time. Do not change file or piece
 priorities for torrents in share mode, it will make it not work.
    
-
    The share mode has one setting, the share ratio target, see session_settings::share_mode_target
-for more info.
    
+
    The share mode has one setting, the share ratio target, see
+session_settings::share_mode_target for more info.
    
     		
 
    
 
    flag_apply_ip_filter
 16
 determines if the IP filter should apply to this torrent or not. By
-default all torrents are subject to filtering by the IP filter (i.e. this flag is set by
-default). This is useful if certain torrents needs to be excempt for some reason, being
-an auto-update torrent for instance.
 
    
 
    flag_paused
 32
 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.
 
    
 
    flag_auto_managed
 64
    If the torrent is auto-managed (flag_auto_managed), the torrent may be resumed
-at any point, regardless of how it paused. If it's important to manually control
-when the torrent is paused and resumed, don't make it auto managed.
    
-
    If flag_auto_managed is set, the torrent will be queued, started and seeded
-automatically by libtorrent. When this is set, the torrent should also be started
-as paused. The default queue order is the order the torrents were added. They
-are all downloaded in that order. For more details, see queuing.
    
-
    If you pass in resume data, the auto_managed state of the torrent when the resume data
-was saved will override the auto_managed state you pass in here. You can override this
-by setting override_resume_data.
    
+
    If the torrent is auto-managed (flag_auto_managed), the torrent
+may be resumed at any point, regardless of how it paused. If it's
+important to manually control when the torrent is paused and
+resumed, don't make it auto managed.
    
+
    If flag_auto_managed is set, the torrent will be queued,
+started and seeded automatically by libtorrent. When this is set,
+the torrent should also be started as paused. The default queue
+order is the order the torrents were added. They are all downloaded
+in that order. For more details, see queuing.
    
+
    If you pass in resume data, the auto_managed state of the torrent
+when the resume data was saved will override the auto_managed state
+you pass in here. You can override this by setting
+override_resume_data.
    
     		
 
    
 
    flag_duplicate_is_error
 
    flag_merge_resume_trackers
 256
 defaults to off and specifies whether tracker URLs loaded from
-resume data should be added to the trackers in the torrent or replace the trackers.
 
    
 
    flag_update_subscribe
 512sets 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.
 
    
 
    flag_sequential_download
 2048sets 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. It has the same
+effect as calling torrent_handle::sequential_download(true) on
+the torrent handle immediately after adding it.
 
    
     
 
    
@@ -272,13 +291,13 @@ is used for forward binary compatibility.
 
 
    
 
    ti
    
-
    torrent_info object with the torrent to add. Unless the url or info_hash
-is set, this is required to be initiazlied.
    
+
    torrent_info object with the torrent to add. Unless the url or
+info_hash is set, this is required to be initiazlied.
    
 
    
 
    
 
    trackers
    
-
    If the torrent doesn't have a tracker, but relies on the DHT to find peers, the
-trackers can specify tracker URLs for the torrent.
    
+
    If the torrent doesn't have a tracker, but relies on the DHT to find
+peers, the trackers can specify tracker URLs for the torrent.
    
 
    
 
    
 
    url_seeds
    
@@ -288,62 +307,71 @@ is set, this is required to be initiazlied.
 
 
    
 
    dht_nodes  name  save_path
    
-
    a list of hostname and port pairs, representing DHT nodes to be
-added to the session (if DHT is enabled). The hostname may be an IP address.
    
+
    a list of hostname and port pairs, representing DHT nodes to be added
+to the session (if DHT is enabled). The hostname may be an IP address.
    
 
    
 
    
 
    resume_data
    
-
    The optional parameter, resume_data can be given if up to date fast-resume data
-is available. The fast-resume data can be acquired from a running torrent by calling
-save_resume_data() on torrent_handle. See fast resume. The vector that is
-passed in will be swapped into the running torrent instance with std::vector::swap().
    
+
    The optional parameter, resume_data can be given if up to date
+fast-resume data is available. The fast-resume data can be acquired
+from a running torrent by calling save_resume_data() on
+torrent_handle. See fast resume. The vector that is passed in
+will be swapped into the running torrent instance with
+std::vector::swap().
    
 
    
 
    
 
    storage_mode
    
-
    One of the values from storage_mode_t. For more information, see storage allocation.
    
+
    One of the values from storage_mode_t. For more information, see
+storage allocation.
    
 
    
 
    
 
    storage
    
-
    can be used to customize how the data is stored. The default
-storage will simply write the data to the files it belongs to, but it could be
-overridden to save everything to a single file at a specific location or encrypt the
-content on disk for instance. For more information about the storage_interface
-that needs to be implemented for a custom storage, see storage_interface.
    
+
    can be used to customize how the data is stored. The default storage
+will simply write the data to the files it belongs to, but it could be
+overridden to save everything to a single file at a specific location
+or encrypt the content on disk for instance. For more information
+about the storage_interface that needs to be implemented for a custom
+storage, see storage_interface.
    
 
    
 
    
 
    userdata
    
-
    The userdata parameter is optional and will be passed on to the extension
-constructor functions, if any (see add_extension()).
    
+
    The userdata parameter is optional and will be passed on to the
+extension constructor functions, if any (see add_extension()).
    
 
    
 
    
 
    file_priorities
    
-
    can be set to control the initial file priorities when adding
-a torrent. The semantics are the same as for torrent_handle::prioritize_files().
    
+
    can be set to control the initial file priorities when adding a
+torrent. The semantics are the same as for
+torrent_handle::prioritize_files().
    
 
    
 
    
 
    trackerid
    
-
    the default tracker id to be used when announcing to trackers. By default
-this is empty, and no tracker ID is used, since this is an optional argument. If
-a tracker returns a tracker ID, that ID is used instead of this.
    
+
    the default tracker id to be used when announcing to trackers. By
+default this is empty, and no tracker ID is used, since this is an
+optional argument. If a tracker returns a tracker ID, that ID is used
+instead of this.
    
 
    
 
    
 
    url
    
-
    If you specify a url, the torrent will be set in downloading_metadata state
-until the .torrent file has been downloaded. If there's any error while downloading,
-the torrent will be stopped and the torrent error state (torrent_status::error)
-will indicate what went wrong. The url may refer to a magnet link or a regular
-http URL.
    
-
    If it refers to an HTTP URL, the info-hash for the added torrent will not be the
-true info-hash of the .torrent. Instead a placeholder, unique, info-hash is used
-which is later updated once the .torrent file has been downloaded.
    
+
    If you specify a url, the torrent will be set in
+downloading_metadata state until the .torrent file has been
+downloaded. If there's any error while downloading, the torrent will
+be stopped and the torrent error state (torrent_status::error)
+will indicate what went wrong. The url may refer to a magnet link
+or a regular http URL.
    
+
    If it refers to an HTTP URL, the info-hash for the added torrent will
+not be the true info-hash of the .torrent. Instead a placeholder,
+unique, info-hash is used which is later updated once the .torrent
+file has been downloaded.
    
 
    Once the info-hash change happens, a torrent_update_alert is posted.
    
 
    
 
    
 
    
 
    uuid
    
-
    if uuid is specified, it is used to find duplicates. If another torrent is already
-running with the same UUID as the one being added, it will be considered a duplicate. This
-is mainly useful for RSS feed items which has UUIDs specified.
    
+
    if uuid is specified, it is used to find duplicates. If another
+torrent is already running with the same UUID as the one being added,
+it will be considered a duplicate. This is mainly useful for RSS feed
+items which has UUIDs specified.
    
 
    
 
    
 
    source_feed_url
    
@@ -352,7 +380,8 @@ if it comes from an RSS feed.
 
    
 
    
 
    flags
    
-
    flags controlling aspects of this torrent and how it's added. See flags_t for details.
    
+
    flags controlling aspects of this torrent and how it's added. See
+flags_t for details.
    
 
    
 
    
 
    info_hash
    
@@ -365,14 +394,14 @@ is the only known property of the torrent. i.e. you don't have a
 
 
    
 
    max_uploads  max_connections  upload_limit  download_limit
    
-
    max_uploads, max_connections, upload_limit, download_limit correspond
-to the set_max_uploads(), set_max_connections(), set_upload_limit() and
-set_download_limit() functions on torrent_handle. These values let you initialize
-these settings when the torrent is added, instead of calling these functions immediately
-following adding it.
    
-
    -1 means unlimited on these settings
-just like their counterpart functions
-on torrent_handle
    
+
    max_uploads, max_connections, upload_limit,
+download_limit correspond to the set_max_uploads(),
+set_max_connections(), set_upload_limit() and
+set_download_limit() functions on torrent_handle. These values let
+you initialize these settings when the torrent is added, instead of
+calling these functions immediately following adding it.
    
+
    -1 means unlimited on these settings just like their counterpart
+functions on torrent_handle
    
 
    
 
    
 
    
@@ -385,7 +414,7 @@ relevant for the disk io thread and disk cache.
    
 
     struct cache_status
 {
-   **cache_status** ();
+   cache_status ();
 
    size_type blocks_written;
    size_type writes;
@@ -415,7 +444,7 @@ struct cache_status
 
    
 
    cache_status()
    
 
    -**cache_status** ();
+cache_status ();
 
    
 
    initializes all counters to 0
    
 
    
@@ -531,13 +560,13 @@ is done shutting down.
    
 
     class session_proxy
 {
-   **session_proxy** ();
+   session_proxy ();
 };
 
    
 
    
 
    session_proxy()
    
 
    -**session_proxy** ();
+session_proxy ();
 
    
 
    default constructor, does not refer to any session
 implementation object.
    
@@ -554,18 +583,18 @@ torrents to participate in.
    
 
     class session: public boost::noncopyable
 {
-   **session** (fingerprint const& print = fingerprint("LT"
+   session (fingerprint const& print = fingerprint("LT"
       , LIBTORRENT_VERSION_MAJOR, LIBTORRENT_VERSION_MINOR, 0, 0)
       , int flags = start_default_features | add_default_plugins
       , boost::uint32_t alert_mask = alert::error_notification
       TORRENT_LOGPATH_ARG_DEFAULT);
-   **session** (fingerprint const& print
+   session (fingerprint const& print
       , std::pair<int, int> listen_port_range
       , char const* listen_interface = "0.0.0.0"
       , int flags = start_default_features | add_default_plugins
       , int alert_mask = alert::error_notification
       TORRENT_LOGPATH_ARG_DEFAULT);
-   **~session** ();
+   ~session ();
    void load_state (lazy_entry const& e);
    void save_state (entry& e, boost::uint32_t flags = 0xffffffff) const;
    void refresh_torrent_status (std::vector<torrent_status>* ret
@@ -684,12 +713,12 @@ class session: public boost::noncopyable
 
    
 
    session()
    
 
    -**session** (fingerprint const& print = fingerprint("LT"
+session (fingerprint const& print = fingerprint("LT"
       , LIBTORRENT_VERSION_MAJOR, LIBTORRENT_VERSION_MINOR, 0, 0)
       , int flags = start_default_features | add_default_plugins
       , boost::uint32_t alert_mask = alert::error_notification
       TORRENT_LOGPATH_ARG_DEFAULT);
-**session** (fingerprint const& print
+session (fingerprint const& print
       , std::pair<int, int> listen_port_range
       , char const* listen_interface = "0.0.0.0"
       , int flags = start_default_features | add_default_plugins
@@ -711,12 +740,12 @@ nat-pmp) and default plugins (ut_metadata, ut_pex and smart_ban). The
 default is to start those things. If you do not want them to start,
 pass 0 as the flags parameter.
    
 
    The alert_mask is the same mask that you would send to
-set_alert_mask().
    
+set_alert_mask().
    
 
    
-
    
+
    
 
    ~session()
    
 
    -**~session** ();
+~session ();
 
    
 
    The destructor of session will notify all trackers that our torrents
 have been shut down. If some trackers are down, they will time out.
@@ -998,7 +1027,7 @@ void dht_get_item (sha1_hash const& target);
 
    query the DHT for an immutable item at the target hash.
 the result is posted as a dht_immutable_item_alert.
    
 
    
-
    
+
    
 
    dht_get_item()
    
 
     void dht_get_item (boost::array<char, 32> key
@@ -1020,7 +1049,7 @@ the returned hash is the key that is to be used to look the item
 up agan. It's just the sha-1 hash of the bencoded form of the
 structure.
    
 
    
-
    
+
    
 
    dht_put_item()
    
 
     void dht_put_item (boost::array<char, 32> key
@@ -1210,7 +1239,7 @@ should be the ip-address of the interface you want the listener socket
 bound to. listen_on() returns the error code of the operation in
 ec. If this indicates success, the session is listening on a port
 within the specified range. If it fails, it will also generate an
-appropriate alert (listen_failed_alert).
    
+appropriate alert (listen_failed_alert).
    
 
    If all ports in the specified range fails to be opened for listening,
 libtorrent will try to use port 0 (which tells the operating system to
 pick a port that's free). If that still fails you may see a
@@ -1288,13 +1317,13 @@ void set_proxy (proxy_settings const& s);
 proxy_settings proxy () const;
 
    
 
    These functions sets and queries the proxy settings to be used for the
-session.
    
+session.
    
 
    For more information on what settings are available for proxies, see
 proxy_settings. If the session is not in anonymous mode, proxies that
 aren't working or fail, will automatically be disabled and packets
 will flow without using any proxy. If you want to enforce using a
 proxy, even when the proxy doesn't work, enable anonymous_mode in
-session_settings.
    
+session_settings.
    
 
 
    
 
    
diff --git a/docs/reference-Settings.html b/docs/reference-Settings.html
index 7d77601c8..7b759e6fa 100644
--- a/docs/reference-Settings.html
+++ b/docs/reference-Settings.html
@@ -55,10 +55,10 @@
 
 
    
@@ -69,7 +69,7 @@ direct certain traffic to a proxy.
    
 
     struct proxy_settings
 {
-   **proxy_settings** ();
+   proxy_settings ();
 
    std::string hostname;
    std::string username;
@@ -83,7 +83,7 @@ struct proxy_settings
 
    
 
    proxy_settings()
    
 
    -**proxy_settings** ();
+proxy_settings ();
 
    
 
    defaults constructs proxy settings, initializing it to the default
 settings.
    
@@ -131,9 +131,9 @@ session::get_settings() to get the current settings.
    
 
     struct session_settings
 {
-   **session_settings** (std::string const& user_agent = "libtorrent/"
+   session_settings (std::string const& user_agent = "libtorrent/"
       LIBTORRENT_VERSION);
-   **~session_settings** ();
+   ~session_settings ();
 
    enum io_buffer_mode_t
    {
@@ -336,9 +336,9 @@ struct session_settings
 
    
 
    ~session_settings() session_settings()
    
 
    -**session_settings** (std::string const& user_agent = "libtorrent/"
+session_settings (std::string const& user_agent = "libtorrent/"
       LIBTORRENT_VERSION);
-**~session_settings** ();
+~session_settings ();
 
    
 
    initializes the session_settings to the default settings.
    
 
    
@@ -1179,7 +1179,7 @@ until libtorrent will take it out of the upload mode, to test if the
 error condition has been fixed.
    
 
    libtorrent will only do this automatically for auto managed torrents.
    
 
    You can explicitly take a torrent out of upload only mode using
-set_upload_mode().
    
+set_upload_mode().
    
 
 
    
 
    
@@ -1744,7 +1744,7 @@ socket on the same port as the TCP socket.
    
 
     struct dht_settings
 {
-   **dht_settings** ();
+   dht_settings ();
 
    int max_peers_reply;
    int search_branching;
@@ -1761,10 +1761,10 @@ struct dht_settings
    bool ignore_dark_internet;
 };
 
    
-
    
+
    
 
    dht_settings()
    
 
    -**dht_settings** ();
+dht_settings ();
 
    
 
    initialized dht_settings to the default values
    
 
    
@@ -1859,7 +1859,7 @@ to peer protocol encryption.
    
 
     struct pe_settings
 {
-   **pe_settings** ();
+   pe_settings ();
 
    enum enc_policy
    {
@@ -1881,10 +1881,10 @@ struct pe_settings
    bool prefer_rc4;
 };
 
    
-
    
+
    
 
    pe_settings()
    
 
    -**pe_settings** ();
+pe_settings ();
 
    
 
    initializes the encryption settings with the default vaues
    
 
    
diff --git a/docs/reference-Time.html b/docs/reference-Time.html
index 29e6d7780..43d44ab45 100644
--- a/docs/reference-Time.html
+++ b/docs/reference-Time.html
@@ -55,8 +55,8 @@
 
    
 
    Table of contents
    
 
 
    
 
    This section contains fundamental time types used internally by
@@ -68,7 +68,7 @@ in time.
    
 and they can only be constructed via one of the construction functions
 that take a well defined time unit (seconds, minutes, etc.). They can
 only be turned into well defined time units by the accessor functions
-(total_microseconds(), etc.).
    
+(total_microseconds(), etc.).
    
 
    
 
    Note
    
 
    In a future version of libtorrent, these types will be replaced
diff --git a/docs/reference-Utility.html b/docs/reference-Utility.html
index db5c560b7..8f12a9b47 100644
--- a/docs/reference-Utility.html
+++ b/docs/reference-Utility.html
@@ -67,12 +67,12 @@ in a heap allocated or borrowed array.
    
 
     struct bitfield
 {
-   **bitfield** (int bits);
-   **bitfield** (bitfield const& rhs);
-   **bitfield** (bitfield&& rhs);
-   **bitfield** (int bits, bool val);
-   **bitfield** ();
-   **bitfield** (char const* b, int bits);
+   bitfield (int bits);
+   bitfield (bitfield const& rhs);
+   bitfield (bitfield&& rhs);
+   bitfield (int bits, bool val);
+   bitfield ();
+   bitfield (char const* b, int bits);
    void borrow_bytes (char* b, int bits);
    void assign (char const* b, int bits);
    bool get_bit (int index) const;
@@ -90,12 +90,12 @@ struct bitfield
 
    
 
    bitfield()
    
 
    -**bitfield** (int bits);
-**bitfield** (bitfield const& rhs);
-**bitfield** (bitfield&& rhs);
-**bitfield** (int bits, bool val);
-**bitfield** ();
-**bitfield** (char const* b, int bits);
+bitfield (int bits);
+bitfield (bitfield const& rhs);
+bitfield (bitfield&& rhs);
+bitfield (int bits, bool val);
+bitfield ();
+bitfield (char const* b, int bits);
 
    
 
    constructs a new bitfield. The default constructor creates an empty
 bitfield. bits is the size of the bitfield (specified in bits).
@@ -196,7 +196,7 @@ peer IDs, node IDs etc.
    
 
     class sha1_hash
 {
-   **sha1_hash** ();
+   sha1_hash ();
    static sha1_hash max ();
    static sha1_hash min ();
    explicit sha1_hash (char const* s);
@@ -230,7 +230,7 @@ class sha1_hash
 
    
 
    sha1_hash()
    
 
    -**sha1_hash** ();
+sha1_hash ();
 
    
 
    constructs an all-sero sha1-hash
    
 
    
diff --git a/include/libtorrent/add_torrent_params.hpp b/include/libtorrent/add_torrent_params.hpp
index 7e4c3e77b..e5c2cd353 100644
--- a/include/libtorrent/add_torrent_params.hpp
+++ b/include/libtorrent/add_torrent_params.hpp
@@ -51,29 +51,32 @@ namespace libtorrent
 	class torrent;
 	struct torrent_plugin;
 
-	// The add_torrent_params is a parameter pack for adding torrents to a session.
-	// The key fields when adding a torrent are:
+	// The add_torrent_params is a parameter pack for adding torrents to a
+	// session. The key fields when adding a torrent are:
 	//
 	// * ti - when you have a .torrent file
 	// * url - when you have a magnet link or http URL to the .torrent file
-	// * info_hash - when all you have is an info-hash (this is similar to a magnet link)
+	// * info_hash - when all you have is an info-hash (this is similar to a
+	//   magnet link)
 	//
-	// one of those fields need to be set. Another mandatory field is ``save_path``.
-	// The add_torrent_params object is passed into one of the ``session::add_torrent()``
-	// overloads or ``session::async_add_torrent()``.
+	// one of those fields need to be set. Another mandatory field is
+	// ``save_path``. The add_torrent_params object is passed into one of the
+	// ``session::add_torrent()`` overloads or ``session::async_add_torrent()``.
 	//
-	// If you only specify the info-hash, the torrent file will be downloaded from peers,
-	// which requires them to support the metadata extension. For the metadata extension
-	// to work, libtorrent must be built with extensions enabled (``TORRENT_DISABLE_EXTENSIONS`` must not be
-	// defined). It also takes an optional ``name`` argument. This may be left empty in case no
-	// name should be assigned to the torrent. In case it's not, the name is used for
-	// the torrent as long as it doesn't have metadata. See ``torrent_handle::name``.
+	// If you only specify the info-hash, the torrent file will be downloaded
+	// from peers, which requires them to support the metadata extension. For
+	// the metadata extension to work, libtorrent must be built with extensions
+	// enabled (``TORRENT_DISABLE_EXTENSIONS`` must not be defined). It also
+	// takes an optional ``name`` argument. This may be left empty in case no
+	// name should be assigned to the torrent. In case it's not, the name is
+	// used for the torrent as long as it doesn't have metadata. See
+	// ``torrent_handle::name``.
 	//
 	struct TORRENT_EXPORT add_torrent_params
 	{
-		// The constructor can be used to initialize the storage constructor, which determines
-		// the storage mechanism for the downloaded or seeding data for the torrent. For more
-		// information, see the ``storage`` field.
+		// The constructor can be used to initialize the storage constructor,
+		// which determines the storage mechanism for the downloaded or seeding
+		// data for the torrent. For more information, see the ``storage`` field.
 		add_torrent_params(storage_constructor_type sc = default_storage_constructor)
 			: version(LIBTORRENT_VERSION_NUM)
 #ifndef TORRENT_NO_DEPRECATE
@@ -127,102 +130,118 @@ namespace libtorrent
 		// values for the ``flags`` field
 		enum flags_t
 		{
-			// If ``flag_seed_mode`` is set, libtorrent will assume that all files are present
-			// for this torrent and that they all match the hashes in the torrent file. Each time
-			// a peer requests to download a block, the piece is verified against the hash, unless
-			// it has been verified already. If a hash fails, the torrent will automatically leave
-			// the seed mode and recheck all the files. The use case for this mode is if a torrent
-			// is created and seeded, or if the user already know that the files are complete, this
-			// is a way to avoid the initial file checks, and significantly reduce the startup time.
+			// If ``flag_seed_mode`` is set, libtorrent will assume that all files
+			// are present for this torrent and that they all match the hashes in
+			// the torrent file. Each time a peer requests to download a block,
+			// the piece is verified against the hash, unless it has been verified
+			// already. If a hash fails, the torrent will automatically leave the
+			// seed mode and recheck all the files. The use case for this mode is
+			// if a torrent is created and seeded, or if the user already know
+			// that the files are complete, this is a way to avoid the initial
+			// file checks, and significantly reduce the startup time.
 			// 
-			// Setting ``flag_seed_mode`` on a torrent without metadata (a .torrent file) is a no-op
-			// and will be ignored.
+			// Setting ``flag_seed_mode`` on a torrent without metadata (a
+			// .torrent file) is a no-op and will be ignored.
 			// 
-			// If resume data is passed in with this torrent, the seed mode saved in there will
-			// override the seed mode you set here.
+			// If resume data is passed in with this torrent, the seed mode saved
+			// in there will override the seed mode you set here.
 			flag_seed_mode = 0x001,
 
-			// If ``flag_override_resume_data`` is set, the ``paused`` and ``auto_managed``
-			// state of the torrent are not loaded from the resume data, but the states requested
-			// by the flags in ``add_torrent_params`` will override them.
+			// If ``flag_override_resume_data`` is set, the ``paused`` and
+			// ``auto_managed`` state of the torrent are not loaded from the
+			// resume data, but the states requested by the flags in
+			// ``add_torrent_params`` will override them.
 			//
-			// If you pass in resume data, the paused state of the torrent when the resume data
-			// was saved will override the paused state you pass in here. You can override this
-			// by setting ``flag_override_resume_data``.
+			// If you pass in resume data, the paused state of the torrent when
+			// the resume data was saved will override the paused state you pass
+			// in here. You can override this by setting
+			// ``flag_override_resume_data``.
 			flag_override_resume_data = 0x002,
 
-			// If ``flag_upload_mode`` is set, the torrent will be initialized in upload-mode,
-			// which means it will not make any piece requests. This state is typically entered
-			// on disk I/O errors, and if the torrent is also auto managed, it will be taken out
-			// of this state periodically. This mode can be used to avoid race conditions when
-			// adjusting priorities of pieces before allowing the torrent to start downloading.
+			// If ``flag_upload_mode`` is set, the torrent will be initialized in
+			// upload-mode, which means it will not make any piece requests. This
+			// state is typically entered on disk I/O errors, and if the torrent
+			// is also auto managed, it will be taken out of this state
+			// periodically. This mode can be used to avoid race conditions when
+			// adjusting priorities of pieces before allowing the torrent to start
+			// downloading.
 			// 
-			// If the torrent is auto-managed (``flag_auto_managed``), the torrent will eventually
-			// be taken out of upload-mode, regardless of how it got there. If it's important to
-			// manually control when the torrent leaves upload mode, don't make it auto managed.
+			// If the torrent is auto-managed (``flag_auto_managed``), the torrent
+			// will eventually be taken out of upload-mode, regardless of how it
+			// got there. If it's important to manually control when the torrent
+			// leaves upload mode, don't make it auto managed.
 			flag_upload_mode = 0x004,
 
 			// determines if the torrent should be added in *share mode* or not.
-			// Share mode indicates that we are not interested in downloading the torrent, but
-			// merley want to improve our share ratio (i.e. increase it). A torrent started in
-			// share mode will do its best to never download more than it uploads to the swarm.
-			// If the swarm does not have enough demand for upload capacity, the torrent will
-			// not download anything. This mode is intended to be safe to add any number of torrents
-			// to, without manual screening, without the risk of downloading more than is uploaded.
+			// Share mode indicates that we are not interested in downloading the
+			// torrent, but merley want to improve our share ratio (i.e. increase
+			// it). A torrent started in share mode will do its best to never
+			// download more than it uploads to the swarm. If the swarm does not
+			// have enough demand for upload capacity, the torrent will not
+			// download anything. This mode is intended to be safe to add any
+			// number of torrents to, without manual screening, without the risk
+			// of downloading more than is uploaded.
 			// 
-			// A torrent in share mode sets the priority to all pieces to 0, except for the pieces
-			// that are downloaded, when pieces are decided to be downloaded. This affects the progress
-			// bar, which might be set to "100% finished" most of the time. Do not change file or piece
+			// A torrent in share mode sets the priority to all pieces to 0,
+			// except for the pieces that are downloaded, when pieces are decided
+			// to be downloaded. This affects the progress bar, which might be set
+			// to "100% finished" most of the time. Do not change file or piece
 			// priorities for torrents in share mode, it will make it not work.
 			// 
-			// The share mode has one setting, the share ratio target, see ``session_settings::share_mode_target``
-			// for more info.
+			// The share mode has one setting, the share ratio target, see
+			// ``session_settings::share_mode_target`` for more info.
 			flag_share_mode = 0x008,
 
 			// determines if the IP filter should apply to this torrent or not. By
-			// default all torrents are subject to filtering by the IP filter (i.e. this flag is set by
-			// default). This is useful if certain torrents needs to be excempt for some reason, being
-			// an auto-update torrent for instance.
+			// default all torrents are subject to filtering by the IP filter
+			// (i.e. this flag is set by default). This is useful if certain
+			// torrents needs to be excempt for some reason, being an auto-update
+			// torrent for instance.
 			flag_apply_ip_filter = 0x010,
 
 			// 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.
+			// 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.
 			flag_paused = 0x020,
 
-			// If the torrent is auto-managed (``flag_auto_managed``), the torrent may be resumed
-			// at any point, regardless of how it paused. If it's important to manually control
-			// when the torrent is paused and resumed, don't make it auto managed.
+			// If the torrent is auto-managed (``flag_auto_managed``), the torrent
+			// may be resumed at any point, regardless of how it paused. If it's
+			// important to manually control when the torrent is paused and
+			// resumed, don't make it auto managed.
 			// 
-			// If ``flag_auto_managed`` is set, the torrent will be queued, started and seeded
-			// automatically by libtorrent. When this is set, the torrent should also be started
-			// as paused. The default queue order is the order the torrents were added. They
-			// are all downloaded in that order. For more details, see queuing_.
+			// If ``flag_auto_managed`` is set, the torrent will be queued,
+			// started and seeded automatically by libtorrent. When this is set,
+			// the torrent should also be started as paused. The default queue
+			// order is the order the torrents were added. They are all downloaded
+			// in that order. For more details, see queuing_.
 			// 
-			// If you pass in resume data, the auto_managed state of the torrent when the resume data
-			// was saved will override the auto_managed state you pass in here. You can override this
-			// by setting ``override_resume_data``.
+			// If you pass in resume data, the auto_managed state of the torrent
+			// when the resume data was saved will override the auto_managed state
+			// you pass in here. You can override this by setting
+			// ``override_resume_data``.
 			flag_auto_managed = 0x040,
 			flag_duplicate_is_error = 0x080,
 
 			// defaults to off and specifies whether tracker URLs loaded from
-			// resume data should be added to the trackers in the torrent or replace the trackers.
+			// resume data should be added to the trackers in the torrent or
+			// replace the trackers.
 			flag_merge_resume_trackers = 0x100,
 
 			// on by default and means that this torrent will be part of state
 			// updates when calling post_torrent_updates().
 			flag_update_subscribe = 0x200,
 
-			// 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 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.
 			flag_super_seeding = 0x400,
 
-			// 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. It has the same
+			// effect as calling ``torrent_handle::sequential_download(true)`` on
+			// the torrent handle immediately after adding it.
 			flag_sequential_download = 0x800,
 
 			// internal
@@ -236,87 +255,97 @@ namespace libtorrent
 		// is used for forward binary compatibility.
 		int version;
 
-		// torrent_info object with the torrent to add. Unless the url or info_hash
-		// is set, this is required to be initiazlied.
+		// torrent_info object with the torrent to add. Unless the url or
+		// info_hash is set, this is required to be initiazlied.
 		boost::intrusive_ptr ti;
 
 #ifndef TORRENT_NO_DEPRECATE
 		char const* tracker_url;
 #endif
-		// If the torrent doesn't have a tracker, but relies on the DHT to find peers, the
-		// ``trackers`` can specify tracker URLs for the torrent.
+		// If the torrent doesn't have a tracker, but relies on the DHT to find
+		// peers, the ``trackers`` can specify tracker URLs for the torrent.
 		std::vector trackers;
 
 		// url seeds to be added to the torrent (`BEP 17`_).
 		std::vector url_seeds;
 
-		// a list of hostname and port pairs, representing DHT nodes to be
-		// added to the session (if DHT is enabled). The hostname may be an IP address.
+		// a list of hostname and port pairs, representing DHT nodes to be added
+		// to the session (if DHT is enabled). The hostname may be an IP address.
 		std::vector > dht_nodes;
 		std::string name;
 		std::string save_path;
 
-		// The optional parameter, ``resume_data`` can be given if up to date fast-resume data
-		// is available. The fast-resume data can be acquired from a running torrent by calling
-		// save_resume_data() on torrent_handle. See fast-resume_. The ``vector`` that is
-		// passed in will be swapped into the running torrent instance with ``std::vector::swap()``.
+		// The optional parameter, ``resume_data`` can be given if up to date
+		// fast-resume data is available. The fast-resume data can be acquired
+		// from a running torrent by calling save_resume_data() on
+		// torrent_handle. See fast-resume_. The ``vector`` that is passed in
+		// will be swapped into the running torrent instance with
+		// ``std::vector::swap()``.
 		std::vector resume_data;
 
-		// One of the values from storage_mode_t. For more information, see storage-allocation_.
+		// One of the values from storage_mode_t. For more information, see
+		// storage-allocation_.
 		storage_mode_t storage_mode;
 
-		// can be used to customize how the data is stored. The default
-		// storage will simply write the data to the files it belongs to, but it could be
-		// overridden to save everything to a single file at a specific location or encrypt the
-		// content on disk for instance. For more information about the storage_interface
-		// that needs to be implemented for a custom storage, see storage_interface.
+		// can be used to customize how the data is stored. The default storage
+		// will simply write the data to the files it belongs to, but it could be
+		// overridden to save everything to a single file at a specific location
+		// or encrypt the content on disk for instance. For more information
+		// about the storage_interface that needs to be implemented for a custom
+		// storage, see storage_interface.
 		storage_constructor_type storage;
 
-		// The ``userdata`` parameter is optional and will be passed on to the extension
-		// constructor functions, if any (see `add_extension()`_).
+		// The ``userdata`` parameter is optional and will be passed on to the
+		// extension constructor functions, if any (see `add_extension()`_).
 		void* userdata;
 
-		// can be set to control the initial file priorities when adding
-		// a torrent. The semantics are the same as for ``torrent_handle::prioritize_files()``.
+		// can be set to control the initial file priorities when adding a
+		// torrent. The semantics are the same as for
+		// ``torrent_handle::prioritize_files()``.
 		std::vector file_priorities;
 
-		// torrent extension construction functions can be added to this
-		// vector to have them be added immediately when the torrent is
-		// constructed. This may be desired over the torrent_handle::add_extension()
-		// in order to avoid race conditions. For instance it may be important
-		// to have the plugin catch events that happen very early on after
-		// the torrent is created.
+		// torrent extension construction functions can be added to this vector
+		// to have them be added immediately when the torrent is constructed.
+		// This may be desired over the torrent_handle::add_extension() in order
+		// to avoid race conditions. For instance it may be important to have the
+		// plugin catch events that happen very early on after the torrent is
+		// created.
 		std::vector(torrent*, void*)> >
 			extensions;
 
-		// the default tracker id to be used when announcing to trackers. By default
-		// this is empty, and no tracker ID is used, since this is an optional argument. If
-		// a tracker returns a tracker ID, that ID is used instead of this.
+		// the default tracker id to be used when announcing to trackers. By
+		// default this is empty, and no tracker ID is used, since this is an
+		// optional argument. If a tracker returns a tracker ID, that ID is used
+		// instead of this.
 		std::string trackerid;
 
-		// If you specify a ``url``, the torrent will be set in ``downloading_metadata`` state
-		// until the .torrent file has been downloaded. If there's any error while downloading,
-		// the torrent will be stopped and the torrent error state (``torrent_status::error``)
-		// will indicate what went wrong. The ``url`` may refer to a magnet link or a regular
-		// http URL.
+		// If you specify a ``url``, the torrent will be set in
+		// ``downloading_metadata`` state until the .torrent file has been
+		// downloaded. If there's any error while downloading, the torrent will
+		// be stopped and the torrent error state (``torrent_status::error``)
+		// will indicate what went wrong. The ``url`` may refer to a magnet link
+		// or a regular http URL.
 		// 
-		// If it refers to an HTTP URL, the info-hash for the added torrent will not be the
-		// true info-hash of the .torrent. Instead a placeholder, unique, info-hash is used
-		// which is later updated once the .torrent file has been downloaded.
+		// If it refers to an HTTP URL, the info-hash for the added torrent will
+		// not be the true info-hash of the .torrent. Instead a placeholder,
+		// unique, info-hash is used which is later updated once the .torrent
+		// file has been downloaded.
 		// 
 		// Once the info-hash change happens, a torrent_update_alert is posted.
 		std::string url;
 
-		// if ``uuid`` is specified, it is used to find duplicates. If another torrent is already
-		// running with the same UUID as the one being added, it will be considered a duplicate. This
-		// is mainly useful for RSS feed items which has UUIDs specified.
+		// if ``uuid`` is specified, it is used to find duplicates. If another
+		// torrent is already running with the same UUID as the one being added,
+		// it will be considered a duplicate. This is mainly useful for RSS feed
+		// items which has UUIDs specified.
 		std::string uuid;
 
 		// should point to the URL of the RSS feed this torrent comes from,
 		// if it comes from an RSS feed.
 		std::string source_feed_url;
 
-		// flags controlling aspects of this torrent and how it's added. See flags_t for details.
+		// flags controlling aspects of this torrent and how it's added. See
+		// flags_t for details.
 		boost::uint64_t flags;
 
 		// set this to the info hash of the torrent to add in case the info-hash
@@ -324,15 +353,15 @@ namespace libtorrent
 		// .torrent file nor a magnet link.
 		sha1_hash info_hash;
 
-		// ``max_uploads``, ``max_connections``, ``upload_limit``, ``download_limit`` correspond
-		// to the ``set_max_uploads()``, ``set_max_connections()``, ``set_upload_limit()`` and
-		// ``set_download_limit()`` functions on torrent_handle. These values let you initialize
-		// these settings when the torrent is added, instead of calling these functions immediately
-		// following adding it.
+		// ``max_uploads``, ``max_connections``, ``upload_limit``,
+		// ``download_limit`` correspond to the ``set_max_uploads()``,
+		// ``set_max_connections()``, ``set_upload_limit()`` and
+		// ``set_download_limit()`` functions on torrent_handle. These values let
+		// you initialize these settings when the torrent is added, instead of
+		// calling these functions immediately following adding it.
 		// 
-		// -1 means unlimited on these settings
-		// just like their counterpart functions
-		// on torrent_handle
+		// -1 means unlimited on these settings just like their counterpart
+		// functions on torrent_handle
 		int max_uploads;
 		int max_connections;
 		int upload_limit;
diff --git a/include/libtorrent/alert.hpp b/include/libtorrent/alert.hpp
index 5fb9c81d5..34bbaecc4 100644
--- a/include/libtorrent/alert.hpp
+++ b/include/libtorrent/alert.hpp
@@ -49,24 +49,22 @@ POSSIBILITY OF SUCH DAMAGE.
 
 // OVERVIEW
 //
-// The pop_alert() function on session is the interface for retrieving
-// alerts, warnings, messages and errors from libtorrent. If no alerts have
-// been posted by libtorrent pop_alert() will return a default initialized
-// ``std::auto_ptr`` object. If there is an alert in libtorrent's queue, the alert
-// from the front of the queue is popped and returned.
-// You can then use the alert object and query
+// The pop_alerts() function on session is the main interface for retrieving
+// alerts (warnings, messages and errors from libtorrent). If no alerts have
+// been posted by libtorrent pop_alert() will return an empty list.
 // 
-// By default, only errors are reported. set_alert_mask() can be
-// used to specify which kinds of events should be reported. The alert mask
-// is comprised by bits from the category_t enum.
+// By default, only errors are reported. set_alert_mask() can be used to
+// specify which kinds of events should be reported. The alert mask is
+// comprised by bits from the category_t enum.
 // 
-// Every alert belongs to one or more category. There is a small cost involved in posting alerts. Only
-// alerts that belong to an enabled category are posted. Setting the alert bitmask to 0 will disable
-// all alerts (except those that are non-discardable).
+// Every alert belongs to one or more category. There is a small cost involved
+// in posting alerts. Only alerts that belong to an enabled category are
+// posted. Setting the alert bitmask to 0 will disable all alerts (except those
+// that are non-discardable).
 // 
 // There are other alert base classes that some alerts derive from, all the
-// alerts that are generated for a specific torrent are derived from torrent_alert,
-// and tracker events derive from tracker_alert.
+// alerts that are generated for a specific torrent are derived from
+// torrent_alert, and tracker events derive from tracker_alert.
 //
 
 #ifdef _MSC_VER
diff --git a/include/libtorrent/bitfield.hpp b/include/libtorrent/bitfield.hpp
index a72ef2dc8..eff90b715 100644
--- a/include/libtorrent/bitfield.hpp
+++ b/include/libtorrent/bitfield.hpp
@@ -48,7 +48,7 @@ namespace libtorrent
 	{
 		// constructs a new bitfield. The default constructor creates an empty
 		// bitfield. ``bits`` is the size of the bitfield (specified in bits).
-		// `` val`` is the value to initialize the bits to. If not specified
+		// ``val`` is the value to initialize the bits to. If not specified
 		// all bits are initialized to 0.
 		//
 		// The constructor taking a pointer ``b`` and ``bits`` copies a bitfield
diff --git a/include/libtorrent/identify_client.hpp b/include/libtorrent/identify_client.hpp
index 0c0b6a39a..ed8492b50 100644
--- a/include/libtorrent/identify_client.hpp
+++ b/include/libtorrent/identify_client.hpp
@@ -50,17 +50,18 @@ POSSIBILITY OF SUCH DAMAGE.
 namespace libtorrent
 {
 
-	// This function is declared in the header ````. It can can be used
-	// to extract a string describing a client version from its peer-id. It will recognize most clients
-	// that have this kind of identification in the peer-id.
+	// This function can can be used to extract a string describing a client
+	// version from its peer-id. It will recognize most clients that have this
+	// kind of identification in the peer-id.
 	TORRENT_EXPORT std::string identify_client(const peer_id& p);
 
-	// Returns an optional fingerprint if any can be identified from the peer id. This can be used
-	// to automate the identification of clients. It will not be able to identify peers with non-
-	// standard encodings. Only Azureus style, Shadow's style and Mainline style. This function is
-	// declared in the header ````.
+	// Returns an optional fingerprint if any can be identified from the peer
+	// id. This can be used to automate the identification of clients. It will
+	// not be able to identify peers with non- standard encodings. Only Azureus
+	// style, Shadow's style and Mainline style.
 	TORRENT_EXPORT boost::optional client_fingerprint(peer_id const& p);
 
 }
 
 #endif // TORRENT_IDENTIFY_CLIENT_HPP_INCLUDED
+
diff --git a/include/libtorrent/storage.hpp b/include/libtorrent/storage.hpp
index 567a97495..d7d7a4d8c 100644
--- a/include/libtorrent/storage.hpp
+++ b/include/libtorrent/storage.hpp
@@ -66,9 +66,21 @@ POSSIBILITY OF SUCH DAMAGE.
 
 // OVERVIEW
 //
-// This is an example storage implementation that stores all pieces in a ``std::map``,
-// i.e. in RAM. It's not necessarily very useful in practice, but illustrates the
-// basics of implementing a custom storage.
+// libtorrent provides a customization point for storage of data. By default,
+// (``default_storage``) downloaded files are saved to disk according with the
+// general conventions of bittorrent clients, mimicing the original file layout
+// when the torrent was created. The libtorrent user may define a custom
+// storage to store piece data in a different way.
+// 
+// A custom storage implementation must derive from and implement the
+// storage_interface. You must also provide a function that constructs the
+// custom storage object and provide this function to the add_torrent() call
+// via add_torrent_params. Either passed in to the constructor or by setting
+// the add_torrent_params::storage field.
+// 
+// This is an example storage implementation that stores all pieces in a
+// ``std::map``, i.e. in RAM. It's not necessarily very useful in practice, but
+// illustrates the basics of implementing a custom storage.
 //
 //::
 //
@@ -166,16 +178,16 @@ namespace libtorrent
 
 	// The storage interface is a pure virtual class that can be implemented to
 	// customize how and where data for a torrent is stored. The default storage
-	// implementation uses regular files in the filesystem, mapping the files in the
-	// torrent in the way one would assume a torrent is saved to disk. Implementing
-	// your own storage interface makes it possible to store all data in RAM, or in
-	// some optimized order on disk (the order the pieces are received for instance),
-	// or saving multifile torrents in a single file in order to be able to take
-	// advantage of optimized disk-I/O.
+	// implementation uses regular files in the filesystem, mapping the files in
+	// the torrent in the way one would assume a torrent is saved to disk.
+	// Implementing your own storage interface makes it possible to store all
+	// data in RAM, or in some optimized order on disk (the order the pieces are
+	// received for instance), or saving multifile torrents in a single file in
+	// order to be able to take advantage of optimized disk-I/O.
 	// 
-	// It is also possible to write a thin class that uses the default storage but
-	// modifies some particular behavior, for instance encrypting the data before
-	// it's written to disk, and decrypting it when it's read again.
+	// It is also possible to write a thin class that uses the default storage
+	// but modifies some particular behavior, for instance encrypting the data
+	// before it's written to disk, and decrypting it when it's read again.
 	// 
 	// The storage interface is based on slots, each slot is 'piece_size' number
 	// of bytes. All access is done by writing and reading whole or partial
@@ -183,9 +195,10 @@ namespace libtorrent
 	// does not necessarily correspond to the piece with the same index (in
 	// compact allocation mode it won't).
 	// 
-	// libtorrent comes with two built-in storage implementations; ``default_storage``
-	// and ``disabled_storage``. Their constructor functions are called default_storage_constructor()
-	// and ``disabled_storage_constructor`` respectively. The disabled storage does
+	// libtorrent comes with two built-in storage implementations;
+	// ``default_storage`` and ``disabled_storage``. Their constructor functions
+	// are called default_storage_constructor() and
+	// ``disabled_storage_constructor`` respectively. The disabled storage does
 	// just what it sounds like. It throws away data that's written, and it
 	// reads garbage. It's useful mostly for benchmarking and profiling purpose.
 	//
@@ -195,50 +208,54 @@ namespace libtorrent
 		storage_interface(): m_disk_pool(0), m_settings(0) {}
 
 
-		// This function is called when the storage is to be initialized. The default storage
-		// will create directories and empty files at this point. If ``allocate_files`` is true,
-		// it will also ``ftruncate`` all files to their target size.
+		// This function is called when the storage is to be initialized. The
+		// default storage will create directories and empty files at this point.
+		// If ``allocate_files`` is true, it will also ``ftruncate`` all files to
+		// their target size.
 		//
 		// Returning ``true`` indicates an error occurred.
 		virtual bool initialize(bool allocate_files) = 0;
 
-		// This function is called when first checking (or re-checking) the storage for a torrent.
-		// It should return true if any of the files that is used in this storage exists on disk.
-		// If so, the storage will be checked for existing pieces before starting the download.
+		// This function is called when first checking (or re-checking) the
+		// storage for a torrent. It should return true if any of the files that
+		// is used in this storage exists on disk. If so, the storage will be
+		// checked for existing pieces before starting the download.
 		virtual bool has_any_file() = 0;
 
 
 		// change the priorities of files.
 		virtual void set_file_priority(std::vector const& prio) = 0;
 
-		// These functions should read or write the data in or to the given ``slot`` at the given ``offset``.
-		// It should read or write ``num_bufs`` buffers sequentially, where the size of each buffer
-		// is specified in the buffer array ``bufs``. The file::iovec_t type has the following members::
+		// These functions should read or write the data in or to the given
+		// ``slot`` at the given ``offset``. It should read or write ``num_bufs``
+		// buffers sequentially, where the size of each buffer is specified in
+		// the buffer array ``bufs``. The file::iovec_t type has the following
+		// members::
 		// 
-		//	struct iovec_t
-		//	{
-		//		void* iov_base;
-		//		size_t iov_len;
-		//	};
+		//	struct iovec_t { void* iov_base; size_t iov_len; };
 		// 
-		// The return value is the number of bytes actually read or written, or -1 on failure. If
-		// it returns -1, the error code is expected to be set to
+		// The return value is the number of bytes actually read or written, or
+		// -1 on failure. If it returns -1, the error code is expected to be set
+		// to
 		// 
-		// Every buffer in ``bufs`` can be assumed to be page aligned and be of a page aligned size,
-		// except for the last buffer of the torrent. The allocated buffer can be assumed to fit a
-		// fully page aligned number of bytes though. This is useful when reading and writing the
-		// last piece of a file in unbuffered mode.
+		// Every buffer in ``bufs`` can be assumed to be page aligned and be of a
+		// page aligned size, except for the last buffer of the torrent. The
+		// allocated buffer can be assumed to fit a fully page aligned number of
+		// bytes though. This is useful when reading and writing the last piece
+		// of a file in unbuffered mode.
 		// 
-		// The ``offset`` is aligned to 16 kiB boundries  *most of the time*, but there are rare
-		// exceptions when it's not. Specifically if the read cache is disabled/or full and a
-		// client requests unaligned data, or the file itself is not aligned in the torrent.
-		// Most clients request aligned data.
+		// The ``offset`` is aligned to 16 kiB boundries  *most of the time*, but
+		// there are rare exceptions when it's not. Specifically if the read
+		// cache is disabled/or full and a client requests unaligned data, or the
+		// file itself is not aligned in the torrent. Most clients request
+		// aligned data.
 		virtual int readv(file::iovec_t const* bufs, int slot, int offset, int num_bufs, int flags = file::random_access);
 		virtual int writev(file::iovec_t const* bufs, int slot, int offset, int num_bufs, int flags = file::random_access);
 
-		// This function is called when a read job is queued. It gives the storage wrapper an
-		// opportunity to hint the operating system about this coming read. For instance, the
-		// storage may call ``posix_fadvise(POSIX_FADV_WILLNEED)`` or ``fcntl(F_RDADVISE)``.
+		// This function is called when a read job is queued. It gives the
+		// storage wrapper an opportunity to hint the operating system about this
+		// coming read. For instance, the storage may call
+		// ``posix_fadvise(POSIX_FADV_WILLNEED)`` or ``fcntl(F_RDADVISE)``.
 		virtual void hint_read(int, int, int) {}
 
 		// negative return value indicates an error
@@ -251,17 +268,18 @@ namespace libtorrent
 		// byte at offset ``offset`` in slot ``slot``.
 		virtual size_type physical_offset(int slot, int offset) = 0;
 
-		// This function is optional. It is supposed to return the first piece, starting at
-		// ``start`` that is fully contained within a data-region on disk (i.e. non-sparse
-		// region). The purpose of this is to skip parts of files that can be known to contain
-		// zeros when checking files.
+		// This function is optional. It is supposed to return the first piece,
+		// starting at ``start`` that is fully contained within a data-region on
+		// disk (i.e. non-sparse region). The purpose of this is to skip parts of
+		// files that can be known to contain zeros when checking files.
 		virtual int sparse_end(int start) const { return start; }
 
-		// This function should move all the files belonging to the storage to the new save_path.
-		// The default storage moves the single file or the directory of the torrent.
+		// This function should move all the files belonging to the storage to
+		// the new save_path. The default storage moves the single file or the
+		// directory of the torrent.
 		// 
-		// Before moving the files, any open file handles may have to be closed, like
-		// ``release_files()``.
+		// Before moving the files, any open file handles may have to be closed,
+		// like ``release_files()``.
 		// 
 		// returns one of:
 		// | no_error = 0
@@ -295,9 +313,10 @@ namespace libtorrent
 		// Returning ``true`` indicates an error occurred.
 		virtual bool move_slot(int src_slot, int dst_slot) = 0;
 
-		// This function should swap the data in ``slot1`` and ``slot2``. The default
-		// storage uses a scratch buffer to read the data into, then moving the other
-		// slot and finally writing back the temporary slot's data
+		// This function should swap the data in ``slot1`` and ``slot2``. The
+		// default storage uses a scratch buffer to read the data into, then
+		// moving the other slot and finally writing back the temporary slot's
+		// data
 		// 
 		// This is only used in compact mode.
 		// 
@@ -305,8 +324,8 @@ namespace libtorrent
 		virtual bool swap_slots(int slot1, int slot2) = 0;
 
 		// This function should do a 3-way swap, or shift of the slots. ``slot1``
-		// should move to ``slot2``, which should be moved to ``slot3`` which in turn
-		// should be moved to ``slot1``.
+		// should move to ``slot2``, which should be moved to ``slot3`` which in
+		// turn should be moved to ``slot1``.
 		// 
 		// This is only used in compact mode.
 		// 
@@ -324,12 +343,13 @@ namespace libtorrent
 		// ``true`` should be returned.
 		virtual bool rename_file(int index, std::string const& new_filename) = 0;
 
-		// This function should delete all files and directories belonging to this storage.
+		// This function should delete all files and directories belonging to
+		// this storage.
 		// 
 		// Returning ``true`` indicates an error occurred.
 		// 
-		// The ``disk_buffer_pool`` is used to allocate and free disk buffers. It has the
-		// following members::
+		// The ``disk_buffer_pool`` is used to allocate and free disk buffers. It
+		// has the following members::
 		//
 		//	struct disk_buffer_pool : boost::noncopyable
 		//	{
@@ -347,13 +367,13 @@ namespace libtorrent
 
 #ifndef TORRENT_NO_DEPRECATE
 		// This function is called each time a file is completely downloaded. The
-		//	storage implementation can perform last operations on a file. The file will
-		//	not be opened for writing after this.
+		// storage implementation can perform last operations on a file. The file
+		// will not be opened for writing after this.
 		//
 		//	``index`` is the index of the file that completed.
 		//	
-		// On windows the default storage implementation clears the sparse file flag
-		//	on the specified file.
+		// On windows the default storage implementation clears the sparse file
+		// flag on the specified file.
 		virtual void finalize_file(int) {}
 #endif
 
@@ -389,9 +409,9 @@ namespace libtorrent
 		session_settings* m_settings;
 	};
 
-	// The default implementation of storage_interface. Behaves as a normal bittorrent client.
-	// It is possible to derive from this class in order to override some of its behavior, when
-	// implementing a custom storage.
+	// The default implementation of storage_interface. Behaves as a normal
+	// bittorrent client. It is possible to derive from this class in order to
+	// override some of its behavior, when implementing a custom storage.
 	class TORRENT_EXPORT default_storage : public storage_interface, boost::noncopyable
 	{
 	public: