documentation updates

docs/gen_reference_doc.py

@@ -302,7 +302,8 @@ def parse_class(lno, lines, filename):
 				else:
 					current_fun['desc'] = context
 					if context == '' and not suppress_warning(filename, first_item(current_fun['names'])):
-						print 'WARNING: member function "%s" is not documented' % (name + '::' + first_item(current_fun['names']))
+						print 'WARNING: member function "%s" is not documented: %s:%d' \
+							% (name + '::' + first_item(current_fun['names']), filename, lno)
 					funs.append(current_fun)
 			context = ''
 			blanks = 0
@@ -318,7 +319,8 @@ def parse_class(lno, lines, filename):
 				fields[-1]['signatures'].append(l)
 			else:
 				if context == '' and not suppress_warning(filename, n):
-					print 'WARNING: field "%s" is not documented' % (name + '::' + n)
+					print 'WARNING: field "%s" is not documented: %s:%d' \
+						% (name + '::' + n, filename, lno)
 				fields.append({'signatures': [l], 'names': [n], 'desc': context})
 			context = ''
 			blanks = 0
@@ -329,7 +331,8 @@ def parse_class(lno, lines, filename):
 			if enum != None and is_visible(context):
 				enum['desc'] = context
 				if context == '' and not suppress_warning(filename, enum['name']):
-					print 'WARNING: enum "%s" is not documented' % (name + '::' + enum['name'])
+					print 'WARNING: enum "%s" is not documented: %s:%d' \
+						% (name + '::' + enum['name'], filename, lno)
 				enums.append(enum)
 			context = ''
 			continue
@@ -550,7 +553,9 @@ for filename in files:
 					current_class, lno = parse_class(lno -1, lines, filename)
 					if current_class != None and is_visible(context):
 						current_class['desc'] = context
-						if context == '': print 'WARNING: class "%s" is not documented' % (current_class['name'])
+						if context == '':
+							print 'WARNING: class "%s" is not documented: %s:%d' \
+							% (current_class['name'], filename, lno)
 						classes.append(current_class)
 				context = ''
 				blanks += 1
@@ -564,7 +569,9 @@ for filename in files:
 						functions[-1]['names'].update(current_fun['names'])
 					else:
 						current_fun['desc'] = context
-						if context == '': print 'WARNING: function "%s" is not documented' % (first_item(current_fun['names']))
+						if context == '':
+							print 'WARNING: function "%s" is not documented: %s:%d' \
+								% (first_item(current_fun['names']), filename, lno)
 						functions.append(current_fun)
 					blanks = 0
 				context = ''
@@ -580,7 +587,9 @@ for filename in files:
 			current_enum, lno = parse_enum(lno - 1, lines, filename)
 			if current_enum != None and is_visible(context):
 				current_enum['desc'] = context
-				if context == '': print 'WARNING: enum "%s" is not documented' % (current_enum['name'])
+				if context == '':
+					print 'WARNING: enum "%s" is not documented: %s:%d' \
+						% (current_enum['name'], filename, lno)
 				enums.append(current_enum)
 			context = ''
 			blanks += 1

include/libtorrent/create_torrent.hpp

@@ -264,10 +264,16 @@ namespace libtorrent
 		void set_priv(bool p) { m_private = p; }
 		bool priv() const { return m_private; }
 
+		// returns the number of pieces in the associated file_storage object.
 		int num_pieces() const { return m_files.num_pieces(); }
+
+		// ``piece_length()`` returns the piece size of all pieces but the
+		// last one. ``piece_size()`` returns the size of the specified piece.
+		// these functions are just forwarding to the associated file_storage.
 		int piece_length() const { return m_files.piece_length(); }
 		int piece_size(int i) const { return m_files.piece_size(i); }
 
+		// internal
 		bool should_add_file_hashes() const { return m_calculate_file_hashes; }
 
 		// This function returns the merkle hash tree, if the torrent was created as a merkle
@@ -417,6 +423,12 @@ namespace libtorrent
 		set_piece_hashes(t, p, detail::nop, ec);
 	}
 #ifndef BOOST_NO_EXCEPTIONS
+	inline void set_piece_hashes(create_torrent& t, std::string const& p)
+	{
+		error_code ec;
+		set_piece_hashes(t, p, detail::nop, ec);
+		if (ec) throw libtorrent_exception(ec);
+	}
 	template <class Fun>
 	void set_piece_hashes(create_torrent& t, std::string const& p, Fun f)
 	{
@@ -424,12 +436,6 @@ namespace libtorrent
 		set_piece_hashes(t, p, f, ec);
 		if (ec) throw libtorrent_exception(ec);
 	}
-	inline void set_piece_hashes(create_torrent& t, std::string const& p)
-	{
-		error_code ec;
-		set_piece_hashes(t, p, detail::nop, ec);
-		if (ec) throw libtorrent_exception(ec);
-	}
 #endif
 
 #if TORRENT_USE_WSTRING

include/libtorrent/file.hpp

@@ -108,7 +108,7 @@ namespace libtorrent
 		int mode;
 	};
 
-	// flags for stat_file
+	// internal flags for stat_file
 	enum { dont_follow_links = 1 };
 	TORRENT_EXTRA_EXPORT void stat_file(std::string f, file_status* s
 		, error_code& ec, int flags = 0);
@@ -182,25 +182,57 @@ namespace libtorrent
 
 	struct TORRENT_EXTRA_EXPORT file: boost::noncopyable, intrusive_ptr_base<file>
 	{
-		enum
+		// the open mode for files. Used for the file constructor or
+		// file::open().
+		enum open_mode_t
 		{
-			// when a file is opened with no_buffer
+			// open the file for reading only
+			read_only = 0,
+
+			// open the file for writing only
+			write_only = 1,
+
+			// open the file for reading and writing
+			read_write = 2,
+			
+			// the mask for the bits determining read or write mode
+			rw_mask = read_only | write_only | read_write,
+
+			// indicate that the file should be opened in
+			// *direct io* mode, i.e. bypassing the operating
+			// system's disk cache, or as much as possible of it
+			// depending on the system.
+			// when a file is opened with no_buffer,
 			// file offsets have to be aligned to
 			// pos_alignment() and buffer addresses
 			// to buf_alignment() and read/write sizes
 			// to size_alignment()
-			read_only = 0,
-			write_only = 1,
-			read_write = 2,
-			rw_mask = read_only | write_only | read_write,
 			no_buffer = 4,
+
+			// open the file in sparse mode (if supported by the
+			// filesystem).
 			sparse = 8,
+
+			// don't update the access timestamps on the file (if
+			// supported by the operating system and filesystem).
+			// this generally improves disk performance.
 			no_atime = 16,
+			
+			// open the file for random acces. This disables read-ahead
+			// logic
 			random_access = 32,
+
+			// prevent the file from being opened by another process
+			// while it's still being held open by this handle
 			lock_file = 64,
 
+			// when creating a file, set the hidden attribute (windows only)
 			attribute_hidden = 0x1000,
+
+			// when creating a file, set the executable attribute
 			attribute_executable = 0x2000,
+
+			// the mask of all attribute bits
 			attribute_mask = attribute_hidden | attribute_executable
 		};
 

include/libtorrent/file_pool.hpp

@@ -63,6 +63,9 @@ namespace libtorrent
 		file_pool(int size = 40);
 		~file_pool();
 
+		// return an open file handle to file at ``file_index`` in the
+		// file_storage ``fs`` opened at save path ``p``. ``m`` is the
+		// file open mode (see file::open_mode_t).
 		boost::intrusive_ptr<file> open_file(void* st, std::string const& p
 			, int file_index, file_storage const& fs, int m, error_code& ec);
 

include/libtorrent/file_storage.hpp

@@ -442,11 +442,27 @@ namespace libtorrent
 		bool pad_file_at(int index) const;
 		size_type file_offset(int index) const;
 
+		// flags indicating various attributes for files in
+		// a file_storage.
 		enum file_flags_t
 		{
+			// this file is a pad file. The creator of the
+			// torrent promises the file is entirely filled with
+			// zeroes and does not need to be downloaded. The
+			// purpose is just to align the next file to either
+			// a block or piece boundary.
 			flag_pad_file = 1,
+
+			// this file is hiddent (sets the hidden attribute
+			// on windows)
 			flag_hidden = 2,
+
+			// this file is executable (sets the executable bit
+			// on posix like systems)
 			flag_executable = 4,
+
+			// this file is a symlink. The symlink target is
+			// specified in a separate field
 			flag_symlink = 8,
 		};