hide some internal functions. error if namespaces are preceded by whitespace (as the docs generation script requires them to start at the beginning of the line)

docs/gen_reference_doc.py

@@ -456,6 +456,9 @@ def parse_class(lno, lines, filename):
                     funs[-1]['signatures'].update(current_fun['signatures'])
                     funs[-1]['names'].update(current_fun['names'])
                 else:
+                    if 'TODO: ' in context:
+                        print('TODO comment in public documentation: %s:%d' % (filename, lno))
+                        sys.exit(1)
                     current_fun['desc'] = context
                     if context == '' and not suppress_warning(filename, first_item(current_fun['names'])):
                         print('WARNING: member function "%s" is not documented: \x1b[34m%s:%d\x1b[0m'
@@ -496,6 +499,9 @@ def parse_class(lno, lines, filename):
             else:
                 enum, lno = parse_enum(lno - 1, lines, filename)
                 if enum is not None:
+                    if 'TODO: ' in context:
+                        print('TODO comment in public documentation: %s:%d' % (filename, lno))
+                        sys.exit(1)
                     enum['desc'] = context
                     if context == '' and not suppress_warning(filename, enum['name']):
                         print('WARNING: enum "%s" is not documented: \x1b[34m%s:%d\x1b[0m'
@@ -767,11 +773,19 @@ for filename in files:
             continue
 
         if (line == 'namespace detail {' or
-                line == 'namespace aux {') \
+                line == 'namespace aux {' or
+                line == 'namespace libtorrent { namespace aux {') \
                 and not internal:
-            lno = consume_block(lno, lines)
+            lno = consume_block(lno - 1, lines)
             continue
 
+        if ('namespace aux' in line or
+                'namespace detail' in line) and \
+                '//' not in line.split('namespace')[0] and \
+                '}' not in line.split('namespace')[1]:
+            print('ERROR: whitespace preceding namespace declaration: %s:%d' % (filename, lno))
+            sys.exit(1)
+
         if 'TORRENT_DEPRECATED' in line:
             if ('class ' in line or 'struct ' in line) and ';' not in line:
                 lno = consume_block(lno - 1, lines)
@@ -786,6 +800,9 @@ for filename in files:
                 if not line.endswith(';'):
                     current_class, lno = parse_class(lno - 1, lines, filename)
                     if current_class is not None and is_visible(context):
+                        if 'TODO: ' in context:
+                            print('TODO comment in public documentation: %s:%d' % (filename, lno))
+                            sys.exit(1)
                         current_class['desc'] = context
                         if context == '':
                             print('WARNING: class "%s" is not documented: \x1b[34m%s:%d\x1b[0m'
@@ -802,6 +819,9 @@ for filename in files:
                         functions[-1]['signatures'].update(current_fun['signatures'])
                         functions[-1]['names'].update(current_fun['names'])
                     else:
+                        if 'TODO: ' in context:
+                            print('TODO comment in public documentation: %s:%d' % (filename, lno))
+                            sys.exit(1)
                         current_fun['desc'] = context
                         if context == '':
                             print('WARNING: function "%s" is not documented: \x1b[34m%s:%d\x1b[0m'
@@ -823,6 +843,9 @@ for filename in files:
             else:
                 current_enum, lno = parse_enum(lno - 1, lines, filename)
                 if current_enum is not None and is_visible(context):
+                    if 'TODO: ' in context:
+                        print('TODO comment in public documentation: %s:%d' % (filename, lno))
+                        sys.exit(1)
                     current_enum['desc'] = context
                     if context == '':
                         print('WARNING: enum "%s" is not documented: \x1b[34m%s:%d\x1b[0m'

include/libtorrent/address.hpp

@@ -65,10 +65,13 @@ namespace libtorrent {
 	using boost::asio::ip::make_address_v4;
 	using boost::asio::ip::make_address_v6;
 #else
+	// internal
 	inline address make_address(string_view str, boost::system::error_code& ec)
 	{ return address::from_string(str.data(), ec); }
+	// internal
 	inline address_v4 make_address_v4(string_view str, boost::system::error_code& ec)
 	{ return address_v4::from_string(str.data(), ec); }
+	// internal
 	inline address_v6 make_address_v6(string_view str, boost::system::error_code& ec)
 	{ return address_v6::from_string(str.data(), ec); }
 #endif

include/libtorrent/block_cache.hpp

@@ -74,6 +74,7 @@ namespace aux {
 
 #if TORRENT_USE_ASSERTS || !defined TORRENT_DISABLE_LOGGING
 
+	// internal
 	struct piece_log_t
 	{
 		explicit piece_log_t(job_action_t j, int b = -1): job(j), block(b) {}
@@ -82,6 +83,7 @@ namespace aux {
 
 		// these are "jobs" thar cause piece_refcount
 		// to be incremented
+		// internal
 		enum artificial_jobs
 		{
 			flushing = static_cast<int>(job_action_t::num_job_ids), // 20

include/libtorrent/disk_buffer_pool.hpp

@@ -49,7 +49,8 @@ POSSIBILITY OF SUCH DAMAGE.
 
 namespace libtorrent {
 
-	namespace aux { struct session_settings; }
+namespace aux { struct session_settings; }
+
 	struct disk_observer;
 
 	struct TORRENT_EXTRA_EXPORT disk_buffer_pool

include/libtorrent/disk_io_thread.hpp

@@ -58,10 +58,7 @@ namespace libtorrent {
 	struct counters;
 	class alert_manager;
 
-namespace aux {
+namespace aux { struct block_cache_reference; }
-
-		struct block_cache_reference;
-	}
 
 	struct cached_piece_info
 	{

include/libtorrent/file_storage.hpp

@@ -528,6 +528,9 @@ namespace libtorrent {
 		// offset to add to any pointers to make them point into the new buffer
 		void apply_pointer_offset(std::ptrdiff_t off);
 
+		// validate any symlinks, to ensure they all point to
+		// other files or directories inside this storage. Any invalid symlinks
+		// are updated to point to themselves.
 		void sanitize_symlinks();
 
 	private:

include/libtorrent/hasher.hpp

@@ -104,6 +104,7 @@ namespace libtorrent {
 		// default constructed.
 		void reset();
 
+		// hidden
 		~hasher();
 
 	private:

include/libtorrent/hasher512.hpp

@@ -104,6 +104,7 @@ namespace libtorrent {
 		// default constructed.
 		void reset();
 
+		// hidden
 		~hasher512();
 
 	private:

include/libtorrent/heterogeneous_queue.hpp

@@ -43,19 +43,18 @@ POSSIBILITY OF SUCH DAMAGE.
 #include "libtorrent/aux_/throw.hpp"
 
 namespace libtorrent {
+namespace aux {
 
-	namespace aux {
+	struct free_deleter
+	{ void operator()(char* ptr) { return std::free(ptr); } };
 
-		struct free_deleter
+	inline std::size_t calculate_pad_bytes(char const* inptr, std::size_t alignment)
-		{ void operator()(char* ptr) { return std::free(ptr); } };
+	{
-
+		std::uintptr_t const ptr = reinterpret_cast<std::uintptr_t>(inptr);
-		inline std::size_t calculate_pad_bytes(char const* inptr, std::size_t alignment)
+		std::uintptr_t const offset = ptr & (alignment - 1);
-		{
+		return (alignment - offset) & (alignment - 1);
-			std::uintptr_t const ptr = reinterpret_cast<std::uintptr_t>(inptr);
-			std::uintptr_t const offset = ptr & (alignment - 1);
-			return (alignment - offset) & (alignment - 1);
-		}
 	}
+}
 
 	template <class T>
 	struct heterogeneous_queue

include/libtorrent/io.hpp

@@ -43,8 +43,8 @@ POSSIBILITY OF SUCH DAMAGE.
 #include "assert.hpp"
 
 namespace libtorrent {
-
 namespace detail {
+
 		template <class T> struct type {};
 
 		// reads an integer from a byte stream
@@ -183,7 +183,7 @@ namespace detail {
 			for (auto const c : val) *out++ = c;
 			return int(val.length());
 		}
-	}
+} // namespace detail
 }
 
 #endif // TORRENT_IO_HPP_INCLUDED

include/libtorrent/packet_pool.hpp

@@ -108,6 +108,7 @@ namespace libtorrent {
 
 	using packet_ptr = std::unique_ptr<packet, packet_deleter>;
 
+	// internal
 	inline packet_ptr create_packet(int const size)
 	{
 		packet* p = static_cast<packet*>(std::malloc(sizeof(packet) + aux::numeric_cast<std::uint16_t>(size)));

include/libtorrent/session_handle.hpp

@@ -102,7 +102,6 @@ namespace libtorrent {
 		static constexpr save_state_flags_t TORRENT_DEPRECATED_MEMBER save_tracker_proxy = 10_bit;
 #endif
 
-		// TODO: 2 the ip filter should probably be saved here too
 		// loads and saves all session settings, including dht_settings,
 		// encryption settings and proxy settings. ``save_state`` writes all keys
 		// to the ``entry`` that's passed in, which needs to either not be

include/libtorrent/settings_pack.hpp

@@ -1167,7 +1167,6 @@ namespace libtorrent {
 			// favour of a choked peer.
 			seeding_piece_quota,
 
-			// TODO: deprecate this
 			// ``max_rejects`` is the number of piece requests we will reject in a
 			// row while a peer is choked before the peer is considered abusive
 			// and is disconnected.

include/libtorrent/socket_io.hpp

@@ -137,7 +137,7 @@ namespace detail {
 			}
 			return ret;
 		}
-	} // namespace detail
+} // namespace detail
 
 }
 

include/libtorrent/storage_defs.hpp

@@ -134,6 +134,8 @@ namespace libtorrent {
 	// it and return garbage for anything read from it.
 	TORRENT_EXPORT storage_interface* disabled_storage_constructor(storage_params const&, file_pool&);
 
+	// the constructor function for the "zero" storage. This will always read
+	// zeroes and ignore all writes.
 	TORRENT_EXPORT storage_interface* zero_storage_constructor(storage_params const&, file_pool&);
 }
 

include/libtorrent/string_view.hpp

@@ -45,6 +45,7 @@ namespace libtorrent {
 using string_view = boost::string_ref;
 using wstring_view = boost::wstring_ref;
 
+// internal
 inline string_view::size_type find_first_of(string_view const v, char const c
 	, string_view::size_type pos)
 {
@@ -56,6 +57,7 @@ inline string_view::size_type find_first_of(string_view const v, char const c
 	return string_view::npos;
 }
 
+// internal
 inline string_view::size_type find_first_of(string_view const v, char const* c
 	, string_view::size_type pos)
 {
@@ -74,12 +76,14 @@ namespace libtorrent {
 using string_view = boost::string_view;
 using wstring_view = boost::wstring_view;
 
+// internal
 inline string_view::size_type find_first_of(string_view const v, char const c
 	, string_view::size_type pos)
 {
 	return v.find_first_of(c, pos);
 }
 
+// internal
 inline string_view::size_type find_first_of(string_view const v, char const* c
 	, string_view::size_type pos)
 {

include/libtorrent/torrent_info.hpp

@@ -125,8 +125,6 @@ namespace libtorrent {
 		int max_decode_tokens = 2000000;
 	};
 
-	// TODO: there may be some opportunities to optimize the size if torrent_info.
-	// specifically to turn some std::string and std::vector into pointers
 	class TORRENT_EXPORT torrent_info
 	{
 	public:
@@ -574,6 +572,9 @@ namespace libtorrent {
 
 	private:
 
+		// TODO: there may be some opportunities to optimize the size if torrent_info.
+		// specifically to turn some std::string and std::vector into pointers
+
 		bool parse_torrent_file(bdecode_node const& libtorrent, error_code& ec);
 		bool parse_torrent_file(bdecode_node const& libtorrent, error_code& ec, int piece_limit);
 

src/session_impl.cpp

@@ -594,6 +594,7 @@ namespace aux {
 #endif
 	}
 
+	// TODO: 2 the ip filter should probably be saved here too
 	void session_impl::save_state(entry* eptr, save_state_flags_t const flags) const
 	{
 		TORRENT_ASSERT(is_single_thread());

src/settings_pack.cpp

@@ -270,6 +270,7 @@ constexpr int CLOSE_FILE_INTERVAL = 0;
 		SET(min_announce_interval, 5 * 60, nullptr),
 		SET(auto_manage_startup, 60, nullptr),
 		SET(seeding_piece_quota, 20, nullptr),
+		// TODO: deprecate this
 		SET(max_rejects, 50, nullptr),
 		SET(recv_socket_buffer_size, 0, &session_impl::update_socket_buffer_size),
 		SET(send_socket_buffer_size, 0, &session_impl::update_socket_buffer_size),