documentation: hide internal functions, include inline functions, support section overviews, hide detail namespace

docs/gen_reference_doc.py

@@ -13,6 +13,9 @@ functions = []
 classes = []
 enums = []
 
+# maps filename to overview description
+overviews = {}
+
 # maps names -> URL
 symbols = {}
 
@@ -73,6 +76,11 @@ def first_item(itr):
 		return i
 	return None
 
+def is_visible(desc):
+	if desc.strip() == 'internal': return False
+	if desc.strip() == 'hidden': return False
+	return True
+
 def highlight_signature(s):
 	name = s.split('(')
 	name2 = name[0].split(' ')
@@ -100,6 +108,7 @@ def looks_like_variable(line):
 	return True
 
 def looks_like_function(line):
+	if '::' in line.split('(')[0].split(' ')[-1]: return False
 	if line.startswith(','): return False
 	if line.startswith(':'): return False
 	return '(' in line;
@@ -177,6 +186,7 @@ def parse_class(lno, lines, filename):
 
 		if l == '':
 			blanks += 1
+			context = ''
 			continue
 
 		if l.startswith('/*'):
@@ -224,7 +234,7 @@ def parse_class(lno, lines, filename):
 
 		if looks_like_function(l):
 			current_fun, lno = parse_function(lno - 1, lines, filename)
-			if current_fun != None and context.strip() != 'internal':
+			if current_fun != None and is_visible(context):
 				if context == '' and blanks == 0 and len(funs):
 					funs[-1]['signatures'].update(current_fun['signatures'])
 					funs[-1]['names'].update(current_fun['names'])
@@ -236,7 +246,7 @@ def parse_class(lno, lines, filename):
 			continue
 
 		if looks_like_variable(l):
-			if context.strip() == 'internal':
+			if not is_visible(context):
 				context = ''
 				continue
 			n = l.split(' ')[-1].split(':')[0].split(';')[0]
@@ -251,7 +261,7 @@ def parse_class(lno, lines, filename):
 
 		if l.startswith('enum '):
 			enum, lno = parse_enum(lno - 1, lines, filename)
-			if enum != None and context.strip() != 'internal':
+			if enum != None and is_visible(context):
 				enum['desc'] = context
 				enums.append(enum)
 			context = ''
@@ -306,7 +316,7 @@ def parse_enum(lno, lines, filename):
 			if verbose: print 'enumv %s' % lines[lno-1]
 			for v in l.split(','):
 				if v == '': continue
-				if context.strip() != 'internal':
+				if is_visible(context):
 					values.append({'name': v.strip(), 'desc': context})
 				context = ''
 		else:
@@ -355,7 +365,9 @@ def consume_ifdef(lno, lines):
 
 	if l == '#ifndef TORRENT_NO_DEPRECATE' or \
 		l == '#ifdef TORRENT_DEBUG' or \
-		(l.startswith('#if') and 'defined TORRENT_DEBUG' in l):
+		l == '#ifdef TORRENT_ASIO_DEBUGGING' or \
+		(l.startswith('#if') and 'defined TORRENT_DEBUG' in l) or \
+		(l.startswith('#if') and 'defined TORRENT_ASIO_DEBUGGING' in l):
 		while lno < len(lines):
 			l = lines[lno].strip()
 			lno += 1
@@ -382,8 +394,22 @@ for filename in files:
 
 		if l == '':
 			blanks += 1
+			context = ''
 			continue
 
+		if l.startswith('//') and l[2:].strip() == 'OVERVIEW':
+			# this is a section overview
+			current_overview = ''
+			while lno < len(lines):
+				l = lines[lno].strip()
+				lno += 1
+				if not l.startswith('//'):
+					# end of overview
+					overviews[filename[11:]] = current_overview
+					current_overview = ''
+					break
+				current_overview += l[2:].strip() + '\n'
+
 		if l.startswith('//'):
 			if verbose: print 'desc  %s' % l
 			l = l.split('//')[1]
@@ -398,6 +424,11 @@ for filename in files:
 			lno = consume_ifdef(lno - 1, lines)
 			continue
 
+		if l == 'namespace detail' or \
+			l == 'namespace aux':
+			lno = consume_block(lno, lines)
+			continue
+
 		if 'TORRENT_CFG' in l:
 			blanks += 1
 			if verbose: print 'xx    %s' % l
@@ -407,10 +438,10 @@ for filename in files:
 			if verbose: print 'xx    %s' % l
 			continue
 
-		if 'TORRENT_EXPORT ' in l:
+		if 'TORRENT_EXPORT ' in l or l.startswith('inline '):
 			if 'class ' in l or 'struct ' in l:
 				current_class, lno = parse_class(lno -1, lines, filename)
-				if current_class != None and context.strip() != 'internal':
+				if current_class != None and is_visible(context):
 					current_class['desc'] = context
 					classes.append(current_class)
 				context = ''
@@ -419,7 +450,7 @@ for filename in files:
 
 			if looks_like_function(l):
 				current_fun, lno = parse_function(lno - 1, lines, filename)
-				if current_fun != None and context.strip() != 'internal':
+				if current_fun != None and is_visible(context):
 					if context == '' and blanks == 0 and len(functions):
 						functions[-1]['signatures'].update(current_fun['signatures'])
 						functions[-1]['names'].update(current_fun['names'])
@@ -438,7 +469,7 @@ for filename in files:
 
 		if l.startswith('enum '):
 			current_enum, lno = parse_enum(lno - 1, lines, filename)
-			if current_enum != None and context.strip() != 'internal':
+			if current_enum != None and is_visible(context):
 				current_enum['desc'] = context
 				enums.append(current_enum)
 			context = ''
@@ -491,6 +522,10 @@ for c in classes:
 	cat = categorize_symbol(c['name'], c['file'])
 	if not cat in categories:
 		categories[cat] = { 'classes': [], 'functions': [], 'enums': [], 'filename': 'reference-%s.html' % cat.replace(' ', '_')}
+
+	if c['file'] in overviews:
+		categories[cat]['overview'] = overviews[c['file']]
+
 	categories[cat]['classes'].append(c)
 	symbols[c['name']] = categories[cat]['filename'] + '#' + html_sanitize(c['name'])
 
@@ -498,6 +533,10 @@ for f in functions:
 	cat = categorize_symbol(first_item(f['names']), f['file'])
 	if not cat in categories:
 		categories[cat] = { 'classes': [], 'functions': [], 'enums': [], 'filename': 'reference-%s.html' % cat.replace(' ', '_')}
+
+	if f['file'] in overviews:
+		categories[cat]['overview'] = overviews[f['file']]
+
 	for n in f['names']:
 		symbols[n] = categories[cat]['filename'] + '#' + html_sanitize(n)
 	categories[cat]['functions'].append(f)
@@ -549,6 +588,9 @@ for cat in categories:
 		<link rel="stylesheet" href="style.css" type="text/css" />
 		</head><body><div id="container">''')
 
+	if 'overview' in categories[cat]:
+		out.write('<h1>%s</h1><p>%s</p>' % (cat, html_sanitize(categories[cat]['overview'])))
+
 	for c in classes:
 		out.write('<a name="%s"></a><h2>%s %s</h2>' % (html_sanitize(c['name']), html_sanitize(c['type']), html_sanitize(c['name'])))
 		print_declared_in(out, c)

include/libtorrent/config.hpp

@@ -333,6 +333,7 @@ POSSIBILITY OF SUCH DAMAGE.
 
 #include <stdarg.h>
 
+// internal
 inline int snprintf(char* buf, int len, char const* fmt, ...)
 {
 	va_list lp;

include/libtorrent/entry.hpp

@@ -215,6 +215,7 @@ namespace libtorrent
 #endif
 
 #ifndef BOOST_NO_EXCEPTIONS
+	// internal
 	inline void throw_type_error()
 	{
 		throw libtorrent_exception(error_code(errors::invalid_entry_type

include/libtorrent/error_code.hpp

@@ -310,15 +310,19 @@ namespace libtorrent
 
 #if BOOST_VERSION < 103500
 	typedef asio::error_code error_code;
+	// hidden
 	inline asio::error::error_category get_posix_category() { return asio::error::system_category; }
+	// hidden
 	inline asio::error::error_category get_system_category() { return asio::error::system_category; }
 
+	// hidden
 	boost::system::error_category const& get_libtorrent_category()
 	{
 		static ::asio::error::error_category libtorrent_category(20);
 		return libtorrent_category;
 	}
 
+	// hidden
 	boost::system::error_category const& get_http_category()
 	{
 		static ::asio::error::error_category http_category(21);
@@ -348,6 +352,7 @@ namespace libtorrent
 
 	namespace errors
 	{
+		// hidden
 		inline boost::system::error_code make_error_code(error_code_enum e)
 		{
 			return boost::system::error_code(e, get_libtorrent_category());
@@ -356,14 +361,15 @@ namespace libtorrent
 
 	using boost::system::error_code;
 
-#if BOOST_VERSION < 104400
+	// hidden
 	inline boost::system::error_category const& get_system_category()
+#if BOOST_VERSION < 104400
 	{ return boost::system::get_system_category(); }
 #else
-	inline boost::system::error_category const& get_system_category()
 	{ return boost::system::system_category(); }
 #endif
 
+	// hidden
 	inline boost::system::error_category const& get_posix_category()
 #if BOOST_VERSION < 103600
 	{ return boost::system::get_posix_category(); }

include/libtorrent/escape_string.hpp

@@ -70,8 +70,8 @@ namespace libtorrent
 	TORRENT_EXTRA_EXPORT std::string read_until(char const*& str, char delim, char const* end);
 	TORRENT_EXTRA_EXPORT int hex_to_int(char in);
 
-	TORRENT_EXPORT std::string to_hex(std::string const& s);
 	TORRENT_EXTRA_EXPORT bool is_hex(char const *in, int len);
+	TORRENT_EXPORT std::string to_hex(std::string const& s);
 	TORRENT_EXPORT void to_hex(char const *in, int len, char* out);
 	TORRENT_EXPORT bool from_hex(char const *in, int len, char* out);
 
@@ -84,7 +84,9 @@ namespace libtorrent
 	TORRENT_EXTRA_EXPORT std::string convert_to_native(std::string const& s);
 	TORRENT_EXTRA_EXPORT std::string convert_from_native(std::string const& s);
 #else
+	// internal
 	inline std::string const& convert_to_native(std::string const& s) { return s; }
+	// internal
 	inline std::string const& convert_from_native(std::string const& s) { return s; }
 #endif		
 }

include/libtorrent/ip_filter.hpp

@@ -56,6 +56,7 @@ POSSIBILITY OF SUCH DAMAGE.
 namespace libtorrent
 {
 
+// hidden
 inline bool operator<=(address const& lhs
 	, address const& rhs)
 {

include/libtorrent/kademlia/node.hpp

@@ -140,11 +140,13 @@ struct dht_mutable_item : dht_immutable_item
 	rsa_key key;
 };
 
+// internal
 inline bool operator<(rsa_key const& lhs, rsa_key const& rhs)
 {
 	return memcmp(lhs.bytes, rhs.bytes, sizeof(lhs.bytes)) < 0;
 }
 
+// internal
 inline bool operator<(peer_entry const& lhs, peer_entry const& rhs)
 {
 	return lhs.addr.address() == rhs.addr.address()

include/libtorrent/ptime.hpp

@@ -55,7 +55,7 @@ namespace libtorrent
 namespace libtorrent
 {
 	// libtorrent time_duration type
-	struct time_duration
+	struct TORRENT_EXPORT time_duration
 	{
 		time_duration() {}
 		time_duration operator/(int rhs) const { return time_duration(diff / rhs); }
@@ -65,6 +65,8 @@ namespace libtorrent
 		time_duration& operator*=(int v) { diff *= v; return *this; }
 		time_duration operator+(time_duration const& c) { return time_duration(diff + c.diff); }
 		time_duration operator-(time_duration const& c) { return time_duration(diff - c.diff); }
+
+		// internal
 		boost::int64_t diff;
 	};
 
@@ -76,12 +78,12 @@ namespace libtorrent
 		ptime& operator+=(time_duration rhs) { time += rhs.diff; return *this; }
 		ptime& operator-=(time_duration rhs) { time -= rhs.diff; return *this; }
 
-		// the internal representation of thie time.
-		// this is using an undefined unit (platform and configuration
-		// dependent).
+		// internal
 		boost::uint64_t time;
 	};
 
+	inline bool is_negative(time_duration dt) { return dt.diff < 0; }
+
 	inline bool operator>(ptime lhs, ptime rhs)
 	{ return lhs.time > rhs.time; }
 	inline bool operator>=(ptime lhs, ptime rhs)
@@ -94,8 +96,6 @@ namespace libtorrent
 	{ return lhs.time != rhs.time;}
 	inline bool operator==(ptime lhs, ptime rhs)
 	{ return lhs.time == rhs.time;}
-
-	inline bool is_negative(time_duration dt) { return dt.diff < 0; }
 	inline bool operator==(time_duration lhs, time_duration rhs)
 	{ return lhs.diff == rhs.diff; }
 	inline bool operator<(time_duration lhs, time_duration rhs)

include/libtorrent/time.hpp

@@ -39,6 +39,24 @@ POSSIBILITY OF SUCH DAMAGE.
 #include <boost/cstdint.hpp>
 #include <string>
 
+// OVERVIEW
+// 
+// This section contains fundamental time types used internall by
+// libtorrent and exposed through various places in the API. The two
+// basic types are ``ptime`` and ``time_duration``. The first represents
+// a point in time and the second the difference between two points
+// in time.
+//
+// The internal representation of these types is implementation defined
+// 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.).
+//
+// .. note::
+// 	In a future version of libtorrent, these types will be replaced
+// 	by the standard timer types from ``std::chrono``.
+
 namespace libtorrent
 {
 	char const* time_now_string();
@@ -64,21 +82,29 @@ namespace libtorrent
 
 #elif TORRENT_USE_CLOCK_GETTIME || TORRENT_USE_SYSTEM_TIME || TORRENT_USE_ABSOLUTE_TIME
 
+	// hidden
 	inline int total_seconds(time_duration td)
 	{ return td.diff / 1000000; }
+	// hidden
 	inline int total_milliseconds(time_duration td)
 	{ return td.diff / 1000; }
+	// hidden
 	inline boost::int64_t total_microseconds(time_duration td)
 	{ return td.diff; }
 
+	// hidden
 	inline time_duration microsec(boost::int64_t s)
 	{ return time_duration(s); }
+	// hidden
 	inline time_duration milliseconds(boost::int64_t s)
 	{ return time_duration(s * 1000); }
+	// hidden
 	inline time_duration seconds(boost::int64_t s)
 	{ return time_duration(s * 1000000); }
+	// hidden
 	inline time_duration minutes(boost::int64_t s)
 	{ return time_duration(s * 1000000 * 60); }
+	// hidden
 	inline time_duration hours(boost::int64_t s)
 	{ return time_duration(s * 1000000 * 60 * 60); }