documentation fixes

This commit is contained in:
Arvid Norberg 2013-08-17 07:01:03 +00:00
parent a5db3ebaaf
commit 2971331f86
6 changed files with 78 additions and 7 deletions

View File

@ -222,18 +222,21 @@ def parse_class(lno, lines, filename):
context = '' context = ''
class_type = 'struct' class_type = 'struct'
blanks = 0 blanks = 0
decl = ''
while lno < len(lines): while lno < len(lines):
l = lines[lno].strip() l = lines[lno].strip()
name += lines[lno].replace('TORRENT_EXPORT ', '').replace('TORRENT_EXTRA_EXPORT', '').split('{')[0].strip() decl += lines[lno].replace('TORRENT_EXPORT ', '').replace('TORRENT_EXTRA_EXPORT', '').split('{')[0].strip()
if '{' in l: break if '{' in l: break
if verbose: print 'class %s' % l if verbose: print 'class %s' % l
lno += 1 lno += 1
if name.startswith('class'): if decl.startswith('class'):
state = 'private' state = 'private'
class_type = 'class' class_type = 'class'
name = decl.split(':')[0].replace('class ', '').replace('struct ', '').strip()
while lno < len(lines): while lno < len(lines):
l = lines[lno].strip() l = lines[lno].strip()
lno += 1 lno += 1
@ -275,7 +278,7 @@ def parse_class(lno, lines, filename):
elif l == 'public:': state = 'public' elif l == 'public:': state = 'public'
if start_brace > 0 and start_brace == end_brace: if start_brace > 0 and start_brace == end_brace:
return [{ 'file': filename[11:], 'enums': enums, 'fields':fields, 'type': class_type, 'name': name.split(':')[0].replace('class ', '').replace('struct ', '').strip(), 'decl': name, 'fun': funs}, lno] return [{ 'file': filename[11:], 'enums': enums, 'fields':fields, 'type': class_type, 'name': name, 'decl': decl, 'fun': funs}, lno]
if state != 'public' and not internal: if state != 'public' and not internal:
if verbose: print 'private %s' % l if verbose: print 'private %s' % l
@ -822,13 +825,13 @@ for cat in categories:
:Version: 1.0.0 :Version: 1.0.0
.. contents:: Table of contents .. contents:: Table of contents
:depth: 2 :depth: 1
:backlinks: none :backlinks: none
''') ''')
if 'overview' in categories[cat]: if 'overview' in categories[cat]:
out.write('%s\n' % categories[cat]['overview']) out.write('%s\n' % linkify_symbols(categories[cat]['overview']))
for c in classes: for c in classes:

View File

@ -231,7 +231,11 @@ namespace libtorrent
// filled in by the constructor and should be left untouched. It // filled in by the constructor and should be left untouched. It
// is used for forward binary compatibility. // is used for forward binary compatibility.
int version; int version;
// 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<torrent_info> ti; boost::intrusive_ptr<torrent_info> ti;
#ifndef TORRENT_NO_DEPRECATE #ifndef TORRENT_NO_DEPRECATE
char const* tracker_url; char const* tracker_url;
#endif #endif

View File

@ -101,6 +101,7 @@ namespace libtorrent
typedef std::list<entry> list_type; typedef std::list<entry> list_type;
typedef size_type integer_type; typedef size_type integer_type;
// the types an entry can have
enum data_type enum data_type
{ {
int_t, int_t,
@ -110,20 +111,28 @@ namespace libtorrent
undefined_t undefined_t
}; };
// returns the concrete type of the entry
data_type type() const; data_type type() const;
// constructors directly from a specific type.
// The content of the argument is copied into the
// newly constructed entry
entry(dictionary_type const&); entry(dictionary_type const&);
entry(string_type const&); entry(string_type const&);
entry(list_type const&); entry(list_type const&);
entry(integer_type const&); entry(integer_type const&);
entry(); // construct an empty entry of the specified type.
// see data_type enum.
entry(data_type t); entry(data_type t);
// hidden
entry(entry const& e); entry(entry const& e);
entry();
~entry(); ~entry();
// hidden
bool operator==(entry const& e) const; bool operator==(entry const& e) const;
void operator=(lazy_entry const&); void operator=(lazy_entry const&);
void operator=(entry const&); void operator=(entry const&);
void operator=(dictionary_type const&); void operator=(dictionary_type const&);
@ -181,6 +190,7 @@ namespace libtorrent
dictionary_type& dict(); dictionary_type& dict();
const dictionary_type& dict() const; const dictionary_type& dict() const;
// swaps the content of *this* with ``e``.
void swap(entry& e); void swap(entry& e);
// All of these functions requires the entry to be a dictionary, if it isn't they // All of these functions requires the entry to be a dictionary, if it isn't they

View File

@ -101,6 +101,8 @@ namespace libtorrent
virtual boost::shared_ptr<peer_plugin> new_connection(peer_connection*) virtual boost::shared_ptr<peer_plugin> new_connection(peer_connection*)
{ return boost::shared_ptr<peer_plugin>(); } { return boost::shared_ptr<peer_plugin>(); }
// called when a piece passes or fails the hash check.
// the argument is the piece index.
virtual void on_piece_pass(int /*index*/) {} virtual void on_piece_pass(int /*index*/) {}
virtual void on_piece_failed(int /*index*/) {} virtual void on_piece_failed(int /*index*/) {}
@ -142,6 +144,8 @@ namespace libtorrent
{ {
virtual ~peer_plugin() {} virtual ~peer_plugin() {}
// This function is expected to return the name of
// the plugin.
virtual char const* type() const { return ""; } virtual char const* type() const { return ""; }
// can add entries to the extension handshake // can add entries to the extension handshake

View File

@ -46,8 +46,10 @@ namespace libtorrent
{ {
struct file; struct file;
// information about a file in a file_storage
struct TORRENT_EXPORT file_entry struct TORRENT_EXPORT file_entry
{ {
// hidden
file_entry(); file_entry();
~file_entry(); ~file_entry();
@ -219,19 +221,39 @@ namespace libtorrent
{ {
friend class torrent_info; friend class torrent_info;
public: public:
// hidden
file_storage(); file_storage();
~file_storage() {} ~file_storage() {}
// returns true if the piece length has been initialized
// on the file_storage. This is typically taken as a proxy
// of whether the file_storage as a whole is initialized or
// not.
bool is_valid() const { return m_piece_length > 0; } bool is_valid() const { return m_piece_length > 0; }
// file attribute flags
enum flags_t enum flags_t
{ {
// the file is a pad file. It's required to contain zeroes
// at it will not be saved to disk. Its purpose is to make
// the following file start on a piece boundary.
pad_file = 1, pad_file = 1,
// this file has the hidden attribute set. This is primarily
// a windows attribute
attribute_hidden = 2, attribute_hidden = 2,
// this file has the executable attribute set.
attribute_executable = 4, attribute_executable = 4,
// this file is a symbilic link. It should have a link
// target string associated with it.
attribute_symlink = 8 attribute_symlink = 8
}; };
// allocates space for ``num_files`` in the internal file list. This can
// be used to avoid reallocating the internal file list when the number
// of files to be added is known up-front.
void reserve(int num_files); void reserve(int num_files);
// Adds a file to the file storage. The ``flags`` argument sets attributes on the file. // Adds a file to the file storage. The ``flags`` argument sets attributes on the file.
@ -252,6 +274,8 @@ namespace libtorrent
void add_file(std::string const& p, size_type size, int flags = 0 void add_file(std::string const& p, size_type size, int flags = 0
, std::time_t mtime = 0, std::string const& s_p = ""); , std::time_t mtime = 0, std::string const& s_p = "");
// renames the file at ``index`` to ``new_filename``. Keep in mind
// that filenames are expected to be UTF-8 encoded.
void rename_file(int index, std::string const& new_filename); void rename_file(int index, std::string const& new_filename);
// this is a low-level function that sets the name of a file // this is a low-level function that sets the name of a file
@ -275,8 +299,15 @@ namespace libtorrent
#endif // TORRENT_NO_DEPRECATE #endif // TORRENT_NO_DEPRECATE
#endif // TORRENT_USE_WSTRING #endif // TORRENT_USE_WSTRING
// returns a list of file_slice objects representing the portions of
// files the specified piece index, byte offset and size range overlaps.
// this is the inverse mapping of map_file().
std::vector<file_slice> map_block(int piece, size_type offset std::vector<file_slice> map_block(int piece, size_type offset
, int size) const; , int size) const;
// returns a peer_request representing the piece index, byte offset
// and size the specified file range overlaps. This is the inverse
// mapping ove map_block().
peer_request map_file(int file, size_type offset, int size) const; peer_request map_file(int file, size_type offset, int size) const;
#ifndef TORRENT_NO_DEPRECATE #ifndef TORRENT_NO_DEPRECATE
@ -307,21 +338,36 @@ namespace libtorrent
file_entry at(iterator i) const TORRENT_DEPRECATED; file_entry at(iterator i) const TORRENT_DEPRECATED;
#endif // TORRENT_NO_DEPRECATE #endif // TORRENT_NO_DEPRECATE
// returns the number of files in the file_storage
int num_files() const int num_files() const
{ return int(m_files.size()); } { return int(m_files.size()); }
// returns a file_entry with information about the file
// at ``index``. Index must be in the range [0, ``num_files()`` ).
file_entry at(int index) const; file_entry at(int index) const;
// returns the total number of bytes all the files in this torrent spans
size_type total_size() const { return m_total_size; } size_type total_size() const { return m_total_size; }
// set and get the number of pieces in the torrent
void set_num_pieces(int n) { m_num_pieces = n; } void set_num_pieces(int n) { m_num_pieces = n; }
int num_pieces() const { TORRENT_ASSERT(m_piece_length > 0); return m_num_pieces; } int num_pieces() const { TORRENT_ASSERT(m_piece_length > 0); return m_num_pieces; }
// set and get the size of each piece in this torrent. This size is typically an even power
// of 2. It doesn't have to be though. It should be divisible by 16kiB however.
void set_piece_length(int l) { m_piece_length = l; } void set_piece_length(int l) { m_piece_length = l; }
int piece_length() const { TORRENT_ASSERT(m_piece_length > 0); return m_piece_length; } int piece_length() const { TORRENT_ASSERT(m_piece_length > 0); return m_piece_length; }
// returns the piece size of ``index``. This will be the same as piece_length(), except
// for the last piece, which may be shorter.
int piece_size(int index) const; int piece_size(int index) const;
// set and get the name of this torrent. For multi-file torrents, this is also
// the name of the root directory all the files are stored in.
void set_name(std::string const& n) { m_name = n; } void set_name(std::string const& n) { m_name = n; }
const std::string& name() const { return m_name; } const std::string& name() const { return m_name; }
// swap all content of *this* with *ti*.
void swap(file_storage& ti) void swap(file_storage& ti)
{ {
using std::swap; using std::swap;

View File

@ -90,6 +90,10 @@ namespace libtorrent
// tracker URL as it appeared in the torrent file // tracker URL as it appeared in the torrent file
std::string url; std::string url;
// the current ``&trackerid=`` argument passed to the tracker.
// this is optional and is normally empty (in which case no
// trackerid is sent).
std::string trackerid; std::string trackerid;
// if this tracker has returned an error or warning message // if this tracker has returned an error or warning message